Documentation

Troubleshooting

A map from symptom to fix for the most common Prometheus issues — MCP, indexer, dashboard, and embeddings.

When something is off, start here. Each section is keyed by what you see, not by what is wrong — so you can jump straight from the log line or the dashboard message to a fix.

MCP server fails to start

Claude Desktop shows no hammer icon, or the prometheus server is greyed out.

Open Claude Desktop → Settings → Developer → Open Logs and look for the prometheus block. The most common cause is a missing PROMETHEUS_API_KEY env entry in the JSON config.
Run the server manually:
```
PROMETHEUS_API_KEY=prom_live_... npx -y @prometheus/context-mcp@latest
```
A healthy boot prints a single line announcing the tool list and then waits on stdin. Any earlier exit is the real error.
If the server exits with 401, the key is wrong, revoked, or scoped to another tenant. Mint a fresh key from /app/api-keys and retry.

`search_code` returns nothing useful

The MCP tool answers but the results look generic or empty.

Confirm the workspace is actually indexed: hit POST /index once and inspect fileCount and symbolCount — both should be non-zero.
Check the language coverage. The parser supports TS, JS, Python, Go, Rust, Java, and C# today. A repo dominated by an unsupported language indexes few or no symbols.
The query may be too short or too generic. The hybrid retriever fuses BM25 with vector similarity, but two-token queries still weight heavily on lexical match. Try a full sentence.
If you recently re-indexed, verify the region and dim in the index response matched the active workspace configuration. A dim mismatch surfaces as a hard error, but a silently retargeted embedder is a corner case worth ruling out.

`POST /index` times out

The request hangs for several minutes and then 504s.

The synchronous worker has a 5-minute hard limit. For repos larger than ~5k files, split with the options.include glob and run two indices, or mail us to enable the async mode (POST /index?async=1) on your workspace.

Dashboard says "Tenant not found"

Sign-in succeeds but /app/dashboard redirects to an error.

The signed prom_tenant cookie points to a tenant you no longer belong to (most often because an admin removed you). The dashboard deliberately fails closed instead of silently swapping you back in. Sign out, sign in again, and the resolver falls back to your first remaining membership.

Invite link is rejected

Redirect	Cause	Fix
`?invite=expired`	Token older than 7 days	Ask the admin to re-invite.
`?invite=already_used`	Invite was already accepted	Sign in normally and switch tenants.
`?invite=revoked`	Admin revoked the invite	Ask for a fresh one.
`?invite=email_mismatch`	Signed-in email differs	Sign out, sign in with the invited address.
`?invite=invalid`	Token malformed	Re-copy the link from the email; do not edit it.

The /invite/{token} route is documented in detail under Members & invitations.

Audit CSV export is empty

Click Export and download a CSV with just the header row.

That is the contract — the export reflects the current filter. Clear the filters (action, status, date range) and re-export, or widen the date range. RLS guarantees you only ever see your own tenant's rows, so an empty export on the widest filter genuinely means no activity.

`429 Too Many Requests`

You hit the per-tenant rate limit. The response carries Retry-After and X-RateLimit-Remaining headers — see Rate limits for the actual budgets and the recommended backoff strategy.

Indexer claims an embedder failure

Response includes EMBED_FAILED or 503 after a long delay.

The default embedding provider is occasionally degraded. The worker has a per-tenant circuit breaker that trips after consecutive failures and recovers after 60 s. Just retry. If you see this for more than ~5 minutes, mail hello@prom.codes — it is almost certainly already on our status feed but a direct ping helps us prioritise.

Still stuck?

Mail hello@prom.codes with:

Your tenant slug (visible top-left in the dashboard).
The HTTP status / error code, if any.
A request id from the worker response or the audit row.
A timestamp in UTC.

That is enough for us to walk our side of the trace. We do not need — and explicitly do not want — your API key or any source code in the report.

MCP server fails to start

search_code returns nothing useful

POST /index times out