> For the complete documentation index, see [llms.txt](https://docs.bountysecurity.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bountysecurity.ai/burp-bounty-server/troubleshooting.md).

# Troubleshooting

Resolve common startup, authentication, catalogue and history problems.

Choose the symptom that matches what you see.

## Startup and authentication

<details>

<summary>Startup license error</summary>

Check `BURPBOUNTY_LICENSE_KEY` in the actual process/service environment, validity and device activation limits.

</details>

<details>

<summary>401, missing X-BURPBOUNTY-LICENSE</summary>

Configure the header in that REST/MCP client. It is also required on `/health`.

</details>

<details>

<summary>401, header does not match</summary>

Use the same key that started this server, not a different valid license.

</details>

<details>

<summary>Client uses X-GBOUNTY-LICENSE</summary>

Reload the renamed/current JAR or update the client header.

</details>

<details>

<summary>No authentication error in the console</summary>

Expected outside debug; the HTTP error still reaches the client.

</details>

## Scanning blocked after startup

A correct client header does not override an expired or revoked subscription. Server rechecks every 15 minutes. An explicit rejection cancels active/paused scans and blocks creation/resume; a temporary service outage has a 24-hour grace period from the last successful validation.

Read the console warning or MCP `server_info.scan_access.reason`, correct the license or connectivity problem, and wait for a successful periodic check. Results remain accessible. Cancelled scans need a new submission after recovery; they are not resumed automatically.

## MCP and profiles

<details>

<summary>/mcp unavailable</summary>

Check `--mcp`, the main port and exact `/mcp` path.

</details>

<details>

<summary>Client asks for OAuth</summary>

This server uses a header credential; disable automatic OAuth where the client supports it.

</details>

<details>

<summary>Empty filtered profile list</summary>

Remove the filter once; check real tags, scanner type and enabled state.

</details>

<details>

<summary>No profiles / directory inaccessible</summary>

Use the server host's absolute `BurpBountyData/profiles` path, not the pack root or ZIP.

</details>

<details>

<summary>cannot unmarshal string ... MatchType ... int</summary>

The supplied profile uses the wrong JSON type. `MatchType` is an integer, not `"Regex"` or `"2"`.

</details>

<details>

<summary>pending_approval</summary>

Operator action is required, or configure intended auto-approval hosts for future runs. Do not treat it as running.

</details>

<details>

<summary>Destination outside approved origins</summary>

A redirect/profile attempted an origin outside the MCP request's explicit services. Check scope rather than silently broadening it.

</details>

<details>

<summary>Marker selection rejected</summary>

Keep one literal `$BBOUNTY$` span and remove incompatible profile transformations; do not retry unmarked.

</details>

## Storage and operation

<details>

<summary>History locked</summary>

Another running process owns that directory. Give each instance its own directory.

</details>

<details>

<summary>History quota or oversized issue</summary>

Check usage/retention and the error. Do not report partial evidence as complete.

</details>

<details>

<summary>/metrics address already in use</summary>

Another process owns port 8082. Change the monitoring port for the additional instance.

</details>

<details>

<summary>Ctrl+C shutdown takes time</summary>

The server is cancelling connections/work and writing results. A second Ctrl+C forces exit.

</details>

## Requests are fewer than the initial total

Compare payload strategy, enabled profiles, insertion points, conditional steps, failed requests, redirects and blind-host coverage. A scan can finish normally while skipping checks that require an unavailable provider. Zero issues only describes the checks that could run.

## REST is still available with --mcp

That is expected: `--mcp` adds another interface on the same listener. It is not a REST/MCP mode switch. The approval gate applies to MCP creation, not to REST submissions.

## Update availability

No update or no published installer produces no notification. A genuine update service/network error can still be logged. It does not mean client header authentication failed and normally does not prevent licensed scanning.

## A lost create response

Check `list_scans` before creating more work. Server has no client-supplied MCP idempotency key; retrying can create a second scan. Keep server alias, scan IDs, timestamps and target selection in the agent's task record.