>unstuck engine

> Troubleshooting

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 mcp with a key) as a fallback.
  • "Not Acceptable" (406) when calling the endpoint by hand. MCP requires Accept: application/json, text/event-stream on 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.