How to Report a Bug in OpenSEO: The Complete Contributor Guide

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, 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:

**Title:** [Bug] <Short description of the failure>

**Description**
I expected the <feature> to <expected behavior>, but it <actual behavior>.

**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:

   pnpm dev:agents

3. Perform the action that triggers the bug (e.g., run a keyword-ranking query via the MCP endpoint):

   curl -X POST http://open-seo.localhost:1355/api/keyword-rank \
        -H "Authorization: Bearer <token>" \
        -d '{"keyword":"open seo","domain":"example.com"}'

4. Observe the error response /logs/dev-server.log snippet:

   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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}