# How to Report a Bug in OpenSEO: A Complete Contributor's Guide

> Learn how to report a bug in OpenSEO by following our complete guide. Submit detailed issues on GitHub with reproduction steps and logs for faster resolution.

- Repository: [Every App/open-seo](https://github.com/every-app/open-seo)
- Tags: how-to-guide
- Published: 2026-09-11

---

**To report a bug in OpenSEO, navigate to the GitHub Issues page, select the bug report template, and submit a detailed issue that includes reproduction steps, environment details from your local setup, and relevant logs from `.logs/dev-server.log`.**

The OpenSEO project encourages community contributions through structured bug reports. When you encounter unexpected behavior in the every-app/open-seo repository, following the documented contribution workflow ensures maintainers can triage and resolve issues efficiently. This guide walks you through how to report a bug in OpenSEO using the official processes defined in [`docs/CONTRIBUTING.md`](https://github.com/every-app/open-seo/blob/main/docs/CONTRIBUTING.md).

## Prerequisites for Submitting Bug Reports

Before opening an issue, collect essential diagnostic information. According to [`docs/CONTRIBUTING.md`](https://github.com/every-app/open-seo/blob/main/docs/CONTRIBUTING.md), the project explicitly invites users to "Open an issue for bugs, UX friction, or feature requests" when problems arise. You should identify the affected feature (rank tracking, keyword research, etc.), note whether you're running Docker, Cloudflare, or a local D1/Postgres setup, and capture any error messages from the console or log files.

## How to Report a Bug in OpenSEO

### Step 1: Gather Context and Environment Details

Document your execution environment precisely. Include your OS, Node.js version, pnpm version, and database backend (D1 or Postgres). Note specific environment variables such as `DATAFORSEO_API_KEY` and `AUTH_MODE` that might influence the bug's behavior. Collect relevant log snippets from `.logs/dev-server.log` or browser developer tools to provide concrete failure evidence.

### Step 2: Create a Minimal Reproduction Case

Isolate the problem to the smallest possible test case. If the bug involves the keyword ranking endpoint, construct a single `curl` request or API call that triggers the failure consistently. Minimal reproductions help maintainers validate fixes quickly without navigating complex project-specific configurations.

### Step 3: Open an Issue Using the Template

Navigate to the repository's Issues page at `https://github.com/every-app/open-seo/issues` and select **New issue**. Use the built-in bug template to structure your report with these components:

- **Title:** Concise summary of the failure
- **Description:** Expected behavior versus actual behavior
- **Steps to Reproduce:** Exact commands (e.g., `pnpm dev:agents`) and API calls
- **Screenshots/Logs:** Attachments from `.logs/dev-server.log` or devtools
- **Environment Details:** OS, Node version, Docker/Cloudflare setup, database backend

### Step 4: Tag and Submit Your Report

Add the label `bug` to your issue—this happens automatically when you select *Bug* in the template. Review your submission for completeness, then submit. Maintainers will triage the report, potentially requesting additional information or linking related discussions.

## Ready-to-Use Issue Template

You can paste this template directly into the GitHub issue form:

```markdown
**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:
   ```sh
   pnpm install
   pnpm run db:migrate:local   # if needed

   ```

2. Start the development server with agents:
   ```sh
   pnpm dev:agents
   ```

3. Perform the action that triggers the bug (e.g., run a keyword-ranking query via the MCP endpoint):
   ```sh
   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 from `.logs/dev-server.log`:
   ```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 Files for Bug Reporting

Understanding these source files helps you provide accurate context:

- **[`docs/CONTRIBUTING.md`](https://github.com/every-app/open-seo/blob/main/docs/CONTRIBUTING.md)** — The official guide directing contributors to open issues for bugs as documented in the OpenSEO repository.
- **[`docs/LOCAL_DEVELOPMENT.md`](https://github.com/every-app/open-seo/blob/main/docs/LOCAL_DEVELOPMENT.md)** — Describes the local development environment, pnpm scripts, and `.env` setup required for reproducing bugs.
- **[`README.md`](https://github.com/every-app/open-seo/blob/main/README.md)** — Provides project overview and links to self-hosting documentation that can affect bug manifestation.
- **GitHub Issues** — The actual destination for filing reports at `https://github.com/every-app/open-seo/issues`.

## Summary

- Report bugs in OpenSEO by opening a new issue in the GitHub repository using the bug template.
- Include precise environment details: Node version, OS, database backend (D1 or Postgres), and `AUTH_MODE` settings.
- Provide minimal reproduction steps using specific commands like `pnpm dev:agents` and relevant API calls.
- Attach log files from `.logs/dev-server.log` and screenshots when applicable.
- Reference [`docs/CONTRIBUTING.md`](https://github.com/every-app/open-seo/blob/main/docs/CONTRIBUTING.md) for the official contribution workflow and requirements.

## Frequently Asked Questions

### Where do I report bugs in OpenSEO?

Submit bug reports to the **GitHub Issues** page at `https://github.com/every-app/open-seo/issues`. The project maintainers explicitly invite users to open issues for bugs, UX friction, or feature requests according to [`docs/CONTRIBUTING.md`](https://github.com/every-app/open-seo/blob/main/docs/CONTRIBUTING.md).

### What should I include in an OpenSEO bug report?

Include a concise title, description contrasting expected versus actual behavior, exact steps to reproduce using commands like `pnpm dev:agents`, environment details (Node version, OS, database backend), and relevant log snippets from `.logs/dev-server.log`. Screenshots and information about environment variables like `DATAFORSEO_API_KEY` are also valuable.

### How do I create a minimal reproduction for OpenSEO bugs?

Isolate the issue to the smallest possible test case, such as a single API call using `curl` to the keyword-ranking endpoint or a specific sequence of commands that triggers the error. Remove any project-specific complexity that isn't necessary to demonstrate the failure, ensuring maintainers can reproduce the bug quickly.

### What labels should I use for bug reports in OpenSEO?

Use the label `bug` when submitting your issue. The GitHub template will automatically apply this label when you select the *Bug* option during issue creation, ensuring proper categorization for maintainer triage.