Troubleshooting
Causes and fixes for MCP connection problems and for each error message the Doclight MCP server can return.
Error messages are fixed text and never contain your key or upstream response bodies. When one includes (request_id: ...),
quote it to support.
The server does not appear or will not start
| Symptom | Likely cause | Fix |
|---|---|---|
| Client says "command not found" or spawn error | Bare doclight-mcp is not on the client's PATH | Use the full path to the executable inside your virtual environment. See Installation. |
| No Doclight tools listed | Config file in the wrong place, JSON syntax error, or the client was not restarted | Check the file location for your client, validate the JSON, then fully restart the client. |
| Only read tools appear | The key has read scope, or its scope could not be determined at startup | Create a key with write scope (and workspace authorisation for create_project), then restart the client. |
create_project missing but other write tools present | The key is write but not authorised for a workspace | Create a workspace-scoped write credential. |
| Server starts, then every call fails | Key missing or malformed | See below. |
Error messages
| Message (abridged) | Meaning | Fix |
|---|---|---|
DOCLIGHT_API_KEY is not set | The env block did not reach the server | Set the variable in the client's server configuration, not only in your shell. |
DOCLIGHT_API_KEY is malformed: Doclight keys start with aeok_ | Wrong value, for example the older Settings key or a quoted/truncated secret | Use a scoped credential secret. |
Authentication failed: the Doclight API key is invalid or revoked | HTTP 401 | Create a new credential and update the configuration. |
The key owner's account has no active paid access | HTTP 402 | Check billing in the dashboard. |
The API key lacks the read/write scope | HTTP 403 | Create a key with the needed scope. |
Not found: the brand or run does not exist or is not accessible to this key | HTTP 404 | Use list_brands for valid ids; the key may not cover that brand. |
The API rejected the request parameters (for example an invalid or expired cursor) | HTTP 422 on a read | Start again without cursor; check limit is 1–100. |
The API rejected the arguments as invalid. Check: ... | HTTP 422 on a write | The listed field names are wrong or out of range. |
Rate limit exceeded for this API key; retry after about N seconds | HTTP 429 | Wait for Retry-After. |
The Doclight API had a temporary server error | HTTP 5xx | Try again later. |
The Doclight API timed out / Could not reach the Doclight API | Network or wrong DOCLIGHT_API_URL | Check connectivity and the URL (default https://api.doclight.app). |
This brand has no measurement runs yet. | get_run_status without a run_id on a brand with no runs | Not an error in your setup; start a run first. |
Write-tool errors
| Message (abridged) | Meaning | Fix |
|---|---|---|
Creating projects needs a write key authorized for a workspace | Brand-only credential | Create a workspace-scoped write key. |
The workspace's project limit for its plan is reached | Plan limit | Upgrade or remove a project. |
The tracked-prompt limit for this plan is reached | Plan limit | Upgrade or archive a prompt. |
A project already exists for this domain / This prompt is already tracked | Duplicate | Use the existing one. |
This idempotency key was already used with different arguments | Key reuse with changed input | Use a new key or repeat the original arguments. |
The object created by this idempotency key no longer exists | The earlier result was removed | Use a new key. |
Some of the requested questions do not exist for this brand | Bad question_ids | Use list_questions. |
Archived questions cannot be measured | Archived question in trigger_run | Pick active or paused questions. |
None of the requested providers is enabled for some of the questions | providers does not overlap | Omit providers or choose enabled ones. |
The run was recorded but the queue refused it | dispatch_failed (HTTP 503) | Retry with the same idempotency_key; no extra quota is used. |
trigger_run also returns (not as an error) status: "rejected" when the daily quota is used up
(report_quota_reached) or a run is already in progress (run_in_flight).
Still stuck
Check the key actually works by calling the API directly with curl:
curl -s -H "Authorization: Bearer aeok_xxxxxxxx_yyyyyyyy" https://api.doclight.app/api/v1/credentialA valid key returns its scopes and workspace_scope. If this works but the client does not, the problem is in the client
configuration; if it fails, the problem is the key.
Permissions and limits
Scopes, workspace and brand requirements, paid access, rate limits, idempotency and the quota implications of measurement runs.
SDK
Install and use the published Doclight JavaScript SDKs (npm 0.1.0) to send application telemetry from your Express site, Node.js code or your own MCP server.