Skip to content

error-codes.md

Latest commit

 

History

History
236 lines (171 loc) · 7.01 KB

error-codes.md

File metadata and controls

236 lines (171 loc) · 7.01 KB

Axis CLI API — Error Codes and Actionable Responses

This document covers HTTP API errors, CLI exit conditions, and runtime error events. Each entry includes the cause and an explicit action for the agent to take.

HTTP API Errors

400 Bad Request

Endpoints: POST /prompt, POST /config

Causes:

  • Request body is not valid JSON
  • Missing required field (e.g. content for /prompt, changes for /config)
  • changes array contains invalid path or value type

Actionable Response:

  1. Verify Content-Type header is application/json
  2. Ensure body is valid JSON (no trailing commas, quoted keys)
  3. For /prompt: confirm body has {"content": "<string>"}
  4. For /config: confirm body has {"changes": [{"path": "<string>", "value": <any>}]}
  5. Do NOT retry with the same malformed request

Example error:

{"error": "Bad Request", "message": "Missing required field: content"}

500 Internal Server Error

Endpoints: All endpoints

Causes:

  • Agent process has crashed or is in a bad state
  • World state not yet loaded (first tick pending)
  • Underlying Starknet/Torii connection failure

Actionable Response:

  1. Wait 5 seconds before retrying
  2. Retry up to 3 times
  3. If persistent: check agent stdout for NDJSON error events
  4. Run axis doctor to validate configuration
  5. Restart axis if necessary: axis run --headless --world=<world> --api-port=<port>

ECONNREFUSED / Connection Refused

Type: Network error (not HTTP response)

Causes:

  • Axis is not running
  • --api-port was not specified when starting axis
  • Wrong port number in request URL
  • Axis started but HTTP API not yet initialized

Actionable Response:

  1. Verify axis is running: check process list or PID file
  2. Confirm --api-port=<PORT> was passed to axis run --headless
  3. Wait 2 seconds after launch for HTTP server to initialize
  4. Check the port number matches --api-port value

CLI Error Conditions

"No worlds discovered"

Cause: Axis cannot reach the Cartridge world discovery API.

Actionable Response:

  1. Check network connectivity
  2. Verify CARTRIDGE_API_BASE env var is not overriding to an invalid URL
  3. Try specifying world manually: set RPC_URL, TORII_URL, WORLD_ADDRESS env vars
  4. Run axis doctor for diagnostics

"--world is required for headless mode"

Cause: axis run --headless was invoked without --world=<name>.

Actionable Response:

  1. Determine the world name: run axis worlds to list discovered worlds
  2. Re-run with axis run --headless --world=<discovered-world-name>
  3. Alternatively, set SLOT_NAME=<world-name> in .env to auto-select

"Auth remains pending" / Session Awaiting Approval

Cause: Browser-based auth was initiated but user has not approved.

Actionable Response:

  1. For headless setups, avoid browser auth entirely: use --method=password
  2. If browser auth is required: capture the redirect URL from the browser after approval and complete with: axis auth <world> --redirect-url="<captured-url>"
  3. Or supply base64 session data directly: axis auth <world> --session-data=<base64>
  4. Check status: axis auth <world> --status

"Password auth fails"

Cause: Invalid credentials or account lacks password credential on Cartridge.

Actionable Response:

  1. Verify --username and --password values are correct
  2. Confirm the account has a password credential set in Cartridge Controller
  3. If account only has social login, use browser auth method instead
  4. Do not retry with same credentials; verify via Cartridge dashboard first

"Session expired"

Cause: The stored Cartridge session has expired.

Actionable Response:

  1. Re-authenticate: axis auth <world>
  2. For headless: axis auth <world> --method=password --username=<user> --password=<pass>
  3. Start the axis agent after successful re-auth
  4. Consider increasing session TTL if configurable in Cartridge

NDJSON Event Stream Error Events

Headless mode emits {"type":"error", ...} events to stdout when errors occur.

Error Event Structure

{
  "type": "error",
  "timestamp": "<ISO-8601>",
  "code": "<ERROR_CODE>",
  "message": "<human-readable message>",
  "world": "<world-name>"
}

Common Error Codes in Event Stream

Code Meaning Action
AUTH_EXPIRED Session expired Re-run axis auth <world> and restart
WORLD_DISCONNECTED Lost connection to world RPC/Torii Check network; agent will retry automatically
LLM_ERROR LLM API call failed Check API key validity and quota; MODEL_PROVIDER and API key may need update
TX_FAILED On-chain transaction rejected Check game state; the action may be invalid given current world state
TICK_TIMEOUT Tick took too long Increase tickIntervalMs via POST /config or shell env
RATE_LIMITED LLM provider rate limited Wait for retry; agent should back off automatically
CONFIG_ERROR Invalid configuration value Run axis doctor; check .env file

Configuration Errors

Missing API Key

Symptom: Agent fails to start or LLM calls fail immediately

Cause: ANTHROPIC_API_KEY (or equivalent for other providers) is not set

Actionable Response:

echo "ANTHROPIC_API_KEY=sk-ant-..." >> ~/.eternum-agent/.env
# Or for OpenAI:
echo "MODEL_PROVIDER=openai" >> ~/.eternum-agent/.env
echo "OPENAI_API_KEY=sk-..." >> ~/.eternum-agent/.env

Invalid Model ID

Symptom: LLM requests fail with model-not-found error

Cause: MODEL_ID set to an invalid or deprecated model identifier

Actionable Response:

  1. Remove or update MODEL_ID in .env to use the default or a valid model
  2. Default for Anthropic: claude-sonnet-4-5-20250929

Diagnostics Command

Run axis doctor to validate configuration and check for common issues:

axis doctor

axis doctor checks:

  • API key presence and format
  • World discovery reachability
  • Session validity for all known worlds
  • Runtime directory permissions
  • Binary version

Error Handling Decision Tree

Agent receives error or no response
│
├── HTTP 400
│   └── Fix request body format; do not retry
│
├── HTTP 500
│   ├── Wait 5s, retry up to 3 times
│   └── If still failing: restart axis
│
├── ECONNREFUSED
│   ├── Check axis is running with --api-port
│   └── Wait 2s after launch for HTTP init
│
├── NDJSON error event (type=error)
│   ├── AUTH_EXPIRED → Re-authenticate
│   ├── LLM_ERROR → Check API key + quota
│   ├── TX_FAILED → Verify action is valid in current game state
│   └── WORLD_DISCONNECTED → Wait; agent retries automatically
│
└── CLI error message
    ├── "No worlds discovered" → Check network + CARTRIDGE_API_BASE
    ├── "--world is required" → Add --world=<name> flag
    ├── "Auth pending" → Use --method=password or complete browser flow
    └── "Session expired" → Re-run axis auth <world>