Error reference

Every CLI error follows one rule: it names the next command, never a bare status code or stack. This page documents the real error strings 2.1.0 produces and how exit codes work — for the SDK's typed ProtoboxError classes (for building your own error handling in TypeScript), see SDK: error handling.

Errors are instructions

Every failure maps to one of a small set of causes, and each one prints what to run next instead of what went wrong internally. These are the real strings, captured against 2.1.0:

Rejected or missing key:

✗ Error: Your API key was rejected
   Run 'protobox login' with a key from app.protobox.ai → Settings → API keys

✗ Error: Not logged in
   Run 'protobox login' (or set PROTOBOX_API_KEY)

A tool ran, but its app isn't connected:

✗ Error: SHOPIFY_GETORDER → failed
   Connect first: 'protobox connect shopify'

An app has no managed OAuth credential configured for this workspace:

✗ Error: The platform rejected the input
   No app credentials are configured for 'asana'. Configure a managed OAuth app for this
   integration, or pass appCredentialsId explicitly.

Nothing is listening at a localhost base URL — vs. a non-local one that's unreachable:

✗ Error: Connection failed
   Nothing is listening at http://localhost:4100 — is the local stack up? (make dev)

✗ Error: Connection failed
   Could not reach https://platform.protobox.ai — check your network or PROTOBOX_BASE_URL

An MCP server key was rejected during mcp test:

✗ Error: MCP handshake failed
   The key was rejected — mint a new one: 'protobox mcp keys create'

"Did you mean" suggestions

A not-found lookup on tools get, tools run, and similar name-addressed commands doesn't stop at "not found" — it diffs against everything that exists and suggests the closest match:

protobox tools get NOT_A_TOOL

✗ Error: No tool 'NOT_A_TOOL' found
   Did you mean 'NOTION_APPEND_BLOCK_CHILDREN'? Or list what exists: 'protobox tools'

Exit codes

Exit code is 0 only when the thing you asked for actually succeeded — not just that the platform accepted the request. tools run is the sharpest example: the HTTP call to the platform can return 200 while the tool call itself failed (wrong args, the target app rejected it, the app isn't connected). The CLI reports the verdict, and the exit code follows the verdict, not the transport status:

protobox tools run SHOPIFY_GETORDER -a order_id=1
echo "exit: $?"

✗ Error: SHOPIFY_GETORDER → failed
   Connect first: 'protobox connect shopify'
exit: 1

protobox tools run COINGECKO_PING
echo "exit: $?"

✓ COINGECKO_PING → success in 366ms
  {
    "gecko_says": "(V3) To the Moon!"
  }
exit: 0

This makes &&/|| and set -e do the right thing in scripts without parsing output:

protobox tools run GITHUB_CREATEISSUE -a repo=octocat/hello -a title="Ship it" \
  && echo "issue created" \
  || echo "tool call did not succeed — check protobox tools logs"

--json errors

With --json, a failure is still non-zero, and stdout carries a structured object instead of the colored message — parse it in scripts rather than the human string, which can change wording between releases:

protobox tools get NOT_A_TOOL --json
echo "exit: $?"

{
  "error": "No tool 'NOT_A_TOOL' found",
  "details": "Did you mean 'NOTION_APPEND_BLOCK_CHILDREN'? Or list what exists: 'protobox tools'"
}

exit: 1

Getting help

If a failure isn't covered above:

1. Re-run with --json and capture the exact error text.
2. Confirm the workspace and key with protobox status.
3. For an MCP-specific failure, run protobox mcp test — it isolates the handshake from everything else that could be wrong.

Related