Start with the probe: unstuck auth status (CLI), or ask your assistant
"Who am I connected as?" (it calls whoami). Both name the workspace and the
credential in use, or the exact error code below.
| You see | It means | Fix |
|---|---|---|
auth_missing |
No credential reached the platform | CLI: unstuck auth login or set UNSTUCK_API_KEY. REST: add the Authorization: Bearer header. MCP remote: the client did not complete sign-in — reconnect the connector. Claude Code / Cursor with a key header: the variable behind Bearer $env:… was empty when you added the server — set it in the same shell, claude mcp remove and add again. |
auth_invalid |
The sign-in token is expired or invalid | Reconnect the connector / sign in again in the client (/mcp in Claude Code). |
api_key_invalid |
Not an Unstuck key, or a key that does not exist | Copy the key again from where it was shown (unstk_…, ~51 chars); check for a trailing space or a truncated paste. |
api_key_expired |
The key reached its expiry date | Create a new key (Settings → API keys) and update the tool — an expired key cannot be rotated. |
api_key_revoked |
The key was revoked, or its owner was deactivated, left or was removed from the workspace | Create a new key under an active member's account. |
api_key_suspended |
The key or the workspace is suspended | Contact support. |
scope_denied |
This key may not perform this action | Use a key with wider scopes, or do it in the app. |
role_required (403) |
Your role in the workspace is below what this change needs (details.required) — e.g. auto top-up needs the owner, auto_join an admin |
Ask an owner or admin, or use their key. |
project_required (403) |
The workspace's project is closed or suspended, so its API is off | Contact support. |
billing_delegated (400) |
Billing for this workspace is managed by its project's paying workspace | Make the change from the paying workspace. |
signal_config_invalid (400) |
A running signal config lacks its type's main input (details.field) |
Fill the field, or save the config as draft. |
rate_limit_exceeded (429) |
The workspace's plan limit for this minute/hour is spent | Wait Retry-After seconds; see rate-limits.md. |
plan_upgrade_required (403) |
The feature is not in the workspace's plan | The details.feature names it; upgrade or leave the filter out. |
insufficient_credits (403) |
Not enough credits for a run | Top up or enable auto top-up in Billing. |
duplicate_config (409) |
A live config with the same settings/code exists | details.existing_id — update that one instead of creating. |
mcp_disabled (503) |
The MCP server is switched off for maintenance | Try again later; the API and CLI keep working. |
network_error (CLI exit 3) |
The platform could not be reached | Check connectivity, proxies, and unstuck config get → api_url. |
network_error … Cannot convert argument to a ByteString … value of 8230 (CLI ≤ 0.1.0) |
The key holds a non-ASCII character — usually a pasted placeholder unstk_… with a real ellipsis |
Set the real key (UNSTUCK_API_KEY or unstuck auth login). From 0.1.1 the CLI says this plainly with exit 2 and names the source. |
--args: not valid JSON (Expected property name …) (CLI exit 2) |
Windows PowerShell + npx.cmd stripped the inner double quotes of inline JSON |
Pass --args @file.json or pipe the JSON to --args -. |
--args: not valid JSON (Unexpected token '' …) (CLI ≤ 0.1.0, exit 2) |
The JSON file starts with a UTF-8 byte order mark (Set-Content -Encoding utf8 in PowerShell 5.1) |
Update to CLI 0.1.1 (tolerated), or write the file without a BOM: [IO.File]::WriteAllText("$PWD\x.json", $json). |
error: unknown option '–status' (CLI exit 2) |
The flag was pasted with an en dash instead of two hyphens | Retype the flag as --status. |
Assistant-specific
- "No tools" / the connector shows nothing. The client connected but did
not finish sign-in, or the server address is wrong. It must be exactly
https://mcp.unstuckengine.com/mcp(with/mcp). Reconnect and complete the browser step. - Sign-in page never appears. Pop-ups blocked, or the client is on a plan
without custom connectors. Try the local server (
npx -y @unstuckengine/cli mcpwith a key) as a fallback. - "Not Acceptable" (406) when calling the endpoint by hand. MCP requires
Accept: application/json, text/event-streamon every POST. Real clients send it; curl needs it added. - The assistant changes something without asking. It should not — every write tool's description tells it to confirm first. Tell the assistant to confirm before writes; report the case to us with the request id.
- Claude Desktop
.mcpb: "Node.js not found". Install Node.js 20 or newer from nodejs.org, then reopen the extension.
When contacting support
Send the error code, the X-Request-Id (the CLI prints it as request_id,
the assistant sees it in the tool result) and the approximate time. Never send
the key itself.