# How to Report a Bug in OpenSEO: The Complete Contributor Guide > Learn how to report a bug in OpenSEO on GitHub. Follow our guide for contributors to submit effective bug reports with reproduction cases and environment details. - Repository: [Every App/open-seo](https://github.com/every-app/open-seo) - Tags: how-to-guide - Published: 2026-07-29 --- **To report a bug in the every-app/open-seo repository, open a GitHub Issue using the bug template, providing a minimal reproduction case, environment details, and logs from your dev server.** When you encounter unexpected behavior in OpenSEO, the open-source SEO automation platform, following the established bug reporting workflow ensures maintainers can triage and fix issues efficiently. The project welcomes community-driven bug reports through its GitHub Issues tracker, as documented in the official Contributing guide. ## Where to Report Bugs in OpenSEO The authoritative source for contribution guidelines lives in [`docs/CONTRIBUTING.md`](https://github.com/every-app/open-seo/blob/main/docs/CONTRIBUTING.md), which explicitly instructs users to "Open an issue for bugs, UX friction, or feature requests". All bug reports should be submitted to the GitHub Issues page at `https://github.com/every-app/open-seo/issues`. ## What to Include in Your Bug Report Before opening an issue, gather these essential components: ### 1. Context and Environment Details Identify the affected feature (rank tracking, keyword research, etc.) and document your environment: - Deployment method (Docker, Cloudflare Workers, or local development) - Database backend (D1 or Postgres) - Node.js and pnpm versions - Relevant environment variables (e.g., `DATAFORSEO_API_KEY`, `AUTH_MODE`) ### 2. Minimal Reproduction Steps Isolate the problem into a specific test case. For example, if a keyword ranking query fails, document the exact API endpoint and payload rather than describing general application usage. ### 3. Log Files and Screenshots Attach relevant snippets from `.logs/dev-server.log` or browser devtools output. These logs are typically generated when running `pnpm dev:agents`. ## The Step-by-Step Bug Reporting Process Follow this workflow to ensure your report is actionable: 1. Navigate to the repository's **Issues** page and click **New issue**. 2. Select the **Bug** template (this automatically applies the `bug` label). 3. Fill in the **Title** with a concise summary of the failure. 4. In the **Description**, state what you expected versus what actually happened. 5. Provide **Steps to Reproduce** including exact commands (e.g., `pnpm dev:agents`) and any required environment variables. 6. Attach **Screenshots or Logs** from your local environment. 7. Submit the issue for maintainer triage. ## Copy-Paste Bug Report Template Use this markdown template when filing your issue: ```markdown **Title:** [Bug] **Description** I expected the to , but it . **Steps to Reproduce** 1. Clone the repo and install dependencies: ```bash pnpm install pnpm run db:migrate:local # if needed ``` 2. Start the development server with agents: ```bash pnpm dev:agents ``` 3. Perform the action that triggers the bug (e.g., run a keyword-ranking query via the MCP endpoint): ```bash curl -X POST http://open-seo.localhost:1355/api/keyword-rank \ -H "Authorization: Bearer " \ -d '{"keyword":"open seo","domain":"example.com"}' ``` 4. Observe the error response `/logs/dev-server.log` snippet: ```log ERROR 2024-07-29T12:34:56Z ❌ Unexpected status 500 from DataForSEO ``` **Environment** - OS: macOS 14.2 - Node: v20.11.0 - pnpm: 9.1.0 - Backend: D1 (default) / Postgres (optional) - AUTH_MODE: `local_noauth` **Additional Information** - Screenshot / log file attached. - This bug appears only when the `DATAFORSEO_API_KEY` is set to a test account. ``` ## Key Documentation References Understanding these files helps you write better bug reports: - **[`docs/CONTRIBUTING.md`](https://github.com/every-app/open-seo/blob/main/docs/CONTRIBUTING.md)**: The official guide that mandates opening issues for bugs and feature requests. - **[`docs/LOCAL_DEVELOPMENT.md`](https://github.com/every-app/open-seo/blob/main/docs/LOCAL_DEVELOPMENT.md)**: Contains setup instructions for local development, including pnpm scripts and `.env` configuration essential for reproducing environment-specific bugs. - **[`README.md`](https://github.com/every-app/open-seo/blob/main/README.md)**: Provides project overview and links to self-hosting documentation. ## Summary - Report bugs via GitHub Issues using the built-in bug template. - Include environment details: OS, Node version, database backend (D1/Postgres), and authentication mode. - Provide minimal reproduction steps with exact commands like `pnpm dev:agents`. - Attach logs from `.logs/dev-server.log` and relevant error screenshots. - Reference [`docs/CONTRIBUTING.md`](https://github.com/every-app/open-seo/blob/main/docs/CONTRIBUTING.md) for the official contribution workflow. ## Frequently Asked Questions ### Where do I find the error logs for OpenSEO? Error logs are written to `.logs/dev-server.log` when running the development server. You can also check console output when using `pnpm dev:agents` to start the server with agents enabled. ### What information should I include when reporting a DataForSEO API bug? Include your `DATAFORSEO_API_KEY` environment variable status (masked or noting if using test credentials), the exact API endpoint called, request payload, and the full error response from the service. Note whether the issue occurs only with specific account types. ### Can I report bugs if I'm using Docker or Cloudflare Workers? Yes. Specify your deployment method in the Environment section of your bug report. For Docker, include your compose configuration. For Cloudflare, note whether you're using D1 or Postgres as the backend database. ### What happens after I submit a bug report? Maintainers will triage the issue, potentially requesting additional information or linking related discussions. The `bug` label applied via the template ensures the report enters the standard workflow defined in the project's contribution guidelines.