Troubleshooting

Resolve common startup, authentication, catalogue and history problems.

Choose the symptom that matches what you see.

Startup and authentication

Startup license error

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

401, missing X-BURPBOUNTY-LICENSE

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

401, header does not match

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

Client uses X-GBOUNTY-LICENSE

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

No authentication error in the console

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

MCP and profiles

/mcp unavailable

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

Client asks for OAuth

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

Empty filtered profile list

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

No profiles / directory inaccessible

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

cannot unmarshal string ... MatchType ... int

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

pending_approval

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

Destination outside approved origins

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

Marker selection rejected

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

Storage and operation

History locked

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

History quota or oversized issue

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

/metrics address already in use

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

Ctrl+C shutdown takes time

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

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.