Troubleshooting
Auth and billing
| Symptom | Likely cause | Fix |
|---|---|---|
| 401 on every call | Token incomplete, trimmed, or wrong header shape | Re-copy the full token from API Settings. Cursor / Claude: Authorization: Bearer <token>. Codex: export MASSED_COMPUTE_API_KEY before launching the GUI. |
| 401 then a browser login | Client is using MCP OAuth, not a pasted token | Expected. Finish sign-in and consent. Review the grant under Connected Apps. |
Auth error -32001 on tool calls | Missing/invalid Authorization header | Use exact Authorization: Bearer <token> (capital Bearer). Raw token or lowercase bearer is rejected on tools/call. |
| Tool list missing launch / terminate / SSH writes | Read-only API key or read-only OAuth grant | Expected. Create a full-access key, or reconnect the app and approve full access. |
| Client never shows an OAuth prompt | Token already in config, or old client | Remove the Authorization header if you want OAuth. Confirm the client supports HTTP MCP + OAuth. |
| 402 on launch | Billing not configured | Set recharge amount and threshold under Billing. |
Client setup
| Symptom | Likely cause | Fix |
|---|---|---|
| Cursor shows red MCP status | Bad token, bad JSON, or Cursor older than 0.45 | Fix token/JSON; update Cursor (HTTP MCP needs 0.45+). |
Claude Desktop shows no tools / fails with a raw url | Desktop speaks stdio MCP only | Use the npx -y mcp-remote … bridge on the Claude Desktop tab. Fully quit and reopen. |
| Codex / ChatGPT: enabled but tools auth-fail | Env var not visible to the GUI process | Set MASSED_COMPUTE_API_KEY where the app inherits it (export + launch the app executable from that terminal, or launchctl setenv for the GUI login session). Fully quit first, then launch with that environment; see client setup. bearer_token_env_var alone is useless if the var is unset. |
Inventory and launch
| Symptom | Likely cause | Fix |
|---|---|---|
| Image incompatible error | Image fabric/driver mismatch for the GPU | Pick another image or product. SXM-only images do not run on PCIe cards and vice versa. Use images_list to find a current compatible image, or use the image selected by the setup recipe. |
Launch fails with thin -32602 despite capacity | Capacity race or product/image pairing | Re-check gpu_inventory_list, try the next available SKU, select a compatible imageId from images_list or the setup recipe. |
instances_get with a bad UUID returns [] | Soft miss | Confirm the instance id from instances_list. |
| Rate-limit (429) | Hitting request limits | Wait about a minute and retry. |
Coupon tools say a required field is missing when you passed code | Field name is coupon | Use { "coupon": "..." }, not code. |
Direct HTTP / scripts
| Symptom | Likely cause | Fix |
|---|---|---|
| Python / some HTTP clients get Cloudflare 1010 | Bot User-Agent blocked at the edge | Set a normal browser or curl User-Agent; default Python-urllib is blocked. |
Known eng issues
These are server-side quirks — work around them rather than treating them as setup mistakes:
| Symptom | Workaround |
|---|---|
ssh_keys_create returns -32602 | Use an existing marketplace SSH key for launch. Do not treat create-key as a first-run step. |
recipes_search / recipes_get bad input → -32603 | Retry with a valid query/slug. Empty, unknown, or very long inputs may return an internal error instead of clean validation. |
ssh_keys_delete bad id → {} | Confirm via ssh_keys_list; do not trust an empty object alone. |