> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bugspray.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Resolve common setup and evidence problems without resetting data.

> [accordion] The server cannot bind its port
>
> Inspect listeners and choose a free port, such as `PORT=3738 pnpm dev`. Use that port in your browser, MCP bridge and submission CLI URLs. Leave processes from other tasks running.

> [accordion] Startup ignores my .env file
>
> Node does not automatically load `.env`. Export values in the process environment or inject them through your secret manager. Compose's interpolation behavior is separate. Verify which process/checkout you started before changing configuration.

> [accordion] A remote or production instance refuses startup
>
> Check `QA_SUITE_PUBLIC_URL`, the HTTPS origin, admin password length and REST token length. Remote binding requires deliberate access control. Ensure built assets exist. Follow the [Node guide](https://docs.bugspray.io/self-hosting/node.md); do not bypass validation.

> [accordion] A browser mutation fails Host or origin checks
>
> Use the exact configured public origin and review proxy forwarding. Do not mix localhost and 127.0.0.1 when the configured origin is explicit. A failed boundary check is not a reason to disable request guards.

> [accordion] A finding submission returns 400 or conflict
>
> Fetch `/api/findings/schema`, read field-level errors and verify multipart metadata is JSON text. MCP has stricter verified-reporting requirements. An execution-disabled deployment cannot perform validation-gated repro submission. Preserve the draft and correct the actual failure.

> [accordion] Browser sign-in or repros cannot start
>
> Install Chromium using `pnpm exec playwright install chromium`. Check recording dependencies (`ffmpeg`, and Xvfb for Linux native capture), the explicit execution flag and profile readiness. Use a dedicated profile and product-action-only scripts. A profile failure is not permission to copy cookies into evidence.

> [accordion] MCP tools are missing or planning has no sampler
>
> Reconnect your client, verify the correct deployment URL and discover its capabilities. Local/hosted/bridge toolsets differ. Sampling requires an established negotiated host; stateless hosted sessions may not support it. Review [MCP reference](https://docs.bugspray.io/reference/mcp.md).

> [accordion] Suite inventory is pending, stale or unavailable
>
> Verify discovery configuration, selected repository/product and signed relevant PR delivery. Configuration does not backfill old PRs. Refresh reads status rather than forcing import. A provider outage leaves freshness unverified; a changed PR head supersedes historical inventory. Retain exact bindings.

> [accordion] A saved plan or green historical run is blocked now
>
> Read current head/base/input/catalog/policy and environment diagnostics. An expired independent approval, changed deployment or missing authenticated artifact can invalidate current evidence. Do not relabel a historical pass as current or dispatch automatically after ambiguous delivery. See [PR validation](https://docs.bugspray.io/guides/pr-validation.md).

> [accordion] The container build cannot find a vendor archive
>
> The current Dockerfile installs before copying required vendored inputs. Resolve that packaging prerequisite and validate the image. Use the documented Node path meanwhile; these docs do not claim the current Compose image builds.

> [accordion] An upgrade fails or evidence is missing
>
> Stop and preserve the current state. Keep SQLite, artifacts, profiles, configuration and keys together in recovery planning. Do not delete the database or data directory. Follow [upgrade and recovery](https://docs.bugspray.io/self-hosting/upgrades.md) against isolated restored data.

When reporting a problem, include the exact source commit, runtime version, deployment mode, sanitized error and steps. Keep tokens, profile sessions, private URLs and customer evidence out of public reports. Use the repository's current [security policy](https://github.com/SynclyUS/bugspray/blob/main/SECURITY.md) for sensitive findings.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.