Docs / Operate
Troubleshooting
5 minute read · Updated 2026-09-11
Most failures fall into four buckets: the token, the plan, the wrong workspace, or mistaking a job launch for a result. This page maps symptoms to causes.
Connection and auth
| Symptom | Cause and fix |
|---|---|
| Client shows the server as failed or offline | Usually the header never arrives. Confirm your config sends Authorization exactly as "Bearer artk_…", and that the URL has no trailing slash. |
| 401 Missing bearer token | No Authorization header reached the server. In Claude Desktop via mcp-remote, check the --header argument is a single string including "Authorization:". |
| 401 Invalid MCP token | The token was revoked, replaced by a newer mint, or truncated on copy. Mint a fresh one in Settings → MCP access. |
| 401 MCP/API access requires the Pro plan or higher | The workspace is not entitled. This is checked per request, so it appears the moment a plan changes. |
| Hand-rolled HTTP request rejected | Send Accept: application/json, text/event-stream. The Streamable HTTP spec requires both types; most clients set it for you, curl does not. |
Tools work but everything is empty
If list_artists returns nothing and the connection is otherwise healthy, the token resolved to a workspace that genuinely has no data. That is nearly always a different account from the one you were looking at in the browser — check which workspace you minted the token from.
Work lands on the wrong artist
The start_* pipeline tools infer the artist from ambient context, which over MCP resolves to the first artist in the workspace. On a workspace holding several artists, that is silently wrong.
Use the run_*_inline variants, which require an explicit artist_id, and read the id from list_artists rather than assuming.
Jobs
| Symptom | Cause and fix |
|---|---|
| The launch "worked" but there is no video | A job tool returns only { job_id }. Poll get_job until status is completed; the assets are in result. |
| Job sits in pending for a minute or two | The render worker scales to zero and is waking. Keep polling. |
| Job failed with no obvious reason | Read both error and the last log event from get_job — the log usually names the stage that broke. The credit reservation is already refunded. |
| Two identical renders appeared | A slow job was relaunched. Wait for a terminal status instead; use list_jobs to see what is already running. |
A tool the docs mention is not available
Your connection is probably in dynamic or explicit toolset mode, so the folder holding it has not been opened. Call list_toolsets to see what is enabled, then enable_toolset with the folder id.
If you did not configure toolsets at all, check the URL your client is using for a ?toolsets= query parameter left over from an earlier setup.
Still stuck
Call health_check first — it isolates the connection from everything else. If that succeeds and a specific tool still misbehaves, get in touch through the contact page with the tool name, the arguments you sent, and the job id if there is one.
Keep going