Docs navigation

Troubleshooting

Error codes, exit codes, and the machine-readable error shape.

Every command supports --output json; on failure it returns a typed error code so an agent can branch on the code instead of parsing prose. Most first-run failures are auth-related — see Authentication.

Error codes

Code	Meaning	Fix
UNAUTHENTICATED	Your key did not resolve to a user.	Use an ipbot_live_… key (private beta) in IPBOT_API_KEY. Check with `ipbot auth whoami`.
INSUFFICIENT_WINDS	Not enough Winds for this Power.	Top up (`ipbot winds topup`) or wait for the weekly refill. The error includes windsCost / balance / shortBy.
PAID_ONLY	Power requires a paid tier.	Upgrade your plan; some Powers (research, video) are paid-tier only.
UNKNOWN_POWER	No Power with that id.	Re-run `ipbot powers list` — ids can change; never hardcode a stale id.
BAD_REQUEST	Invalid input or missing required arg.	Check the Power input is valid JSON; supply --user-id / IPBOT_USER_ID for user-scoped commands.
FORBIDDEN	Authenticated, but not allowed.	You lack access to this org/account/draft, or are reviewing your own draft without --allow-self-review.
UNKNOWN_OPERATION	Unknown tool/command name.	Check the command/tool name against `ipbot --help` or the MCP tool list.
INTERNAL	Unexpected server error.	Retry once; if it persists, capture the message and contact support.

CLI exit codes

Exit	Meaning
0	Success.
1	Unexpected error (transport failure, crash, bad usage).
2	Operation failed or not found (e.g. system status unhealthy, draft not found, schedule failed).
3	Structured Power failure (INSUFFICIENT_WINDS, PAID_ONLY, UNKNOWN_POWER, …) — distinguishable from a crash.
124	Timeout (e.g. `calendar wait` exceeded its deadline).

MCP error shape

When an MCP tool fails it returns a result flagged isError: true whose content is a typed error — not a success-looking payload:

json

{
  "isError": true,
  "content": [
    { "type": "text", "text": "{ \"error\": { \"code\": \"INSUFFICIENT_WINDS\", \"message\": \"...\" } }" }
  ]
}

Common first-run failures

Symptom	Cause & fix
`UNAUTHENTICATED` on first call	No/invalid key. Beta key required — see Authentication.
Content/calendar returns empty	Missing user id. Set IPBOT_USER_ID or pass --user-id; commands now error instead of guessing.
A Power needs an account you haven't connected	Connect it first (`ipbot accounts list` shows canPost / missingScopes per account).
npx can't find the endpoint	Set IPBOT_APPSYNC_ENDPOINT; copy it from Settings → API Keys.