Common Runtime Errors

Quick reference for the most frequently encountered OpenClaw errors, with causes and step-by-step fixes.

Troubleshooting8 min read
⚡
Quick Fix Checklist — Try these first before diving deeper:
  1. Run openclaw --version to confirm installation is working
  2. Check your API key: echo $OPENCLAW_API_KEY (Linux/Mac) or $env:OPENCLAW_API_KEY (Windows)
  3. Verify config file exists: openclaw config show
  4. Try openclaw run "hello" --debug to see verbose error output
  5. Check log files for the full error trace

Error Quick Reference

Error MessageCauseFix
AuthenticationError: Invalid API keyMissing or wrong API keyCheck OPENCLAW_API_KEY env var or config.yaml
RateLimitError: 429 Too Many RequestsAPI quota exceededAdd rate_limit.requests_per_minute in config
TimeoutError: Request timed out after 30sSlow network or modelIncrease timeout_seconds in config
ToolExecutionError: tool 'web_search' failedPack not installedRun openclaw install web
ContextWindowError: Input exceeds max tokensInput too largeUse --chunk-size flag
ConnectionError: Failed to connect to localhost:11434Ollama not runningRun ollama serve
ConfigError: config.yaml not foundRunning from wrong dirPass --config /path/to/config.yaml
ModelNotFoundError: gpt-5 does not existTypo or unavailable modelCheck openclaw config list-models

API Authentication Errors

# Verify your key is set
echo $OPENCLAW_API_KEY

# Test the API key directly
openclaw config test-connection

# Re-set the key
export OPENCLAW_API_KEY="sk-..."
# Or save permanently:
openclaw config set api_key "sk-..."

Rate Limit Errors

# config.yaml
rate_limit:
  requests_per_minute: 15   # Stay under your plan's limit
  retry_on_rate_limit: true
  retry_delay_seconds: 60
  max_retries: 5
📝
Free tier limits

OpenAI free tier: 3 RPM. GPT-4 tier-1: 500 RPM. Use --model gpt-4o-mini for higher limits at lower cost.

Timeout Errors

# config.yaml
timeout_seconds: 120    # default: 30
stream: true            # streaming prevents timeouts on long outputs

Tool Execution Errors

# List installed packs
openclaw config list-packs

# Install missing pack
openclaw install web

# Run with debug to see tool calls
openclaw run "search the web for latest AI news" --debug
💡
See Also

Network & Connection Errors

ErrorCauseFix
ConnectionRefusedError: [Errno 111]Ollama not running on localhostRun ollama serve; check port 11434
SSLError: certificate verify failedCorporate proxy / self-signed certSet ssl_verify: false in config (testing only)
ProxyError: HTTPSConnectionPoolNetwork proxy intercepts HTTPSSet HTTPS_PROXY env var or proxy_url in config
ReadTimeout: did not receive dataSlow API, large contextIncrease timeout_seconds: 180
MaxRetryError: HTTPSConnectionPoolLLM API is downCheck status.openai.com

Test Network Connectivity

# Test OpenAI API reachability
curl -s https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY" | head -50

# Test Ollama locally
curl -s http://localhost:11434/api/tags | python3 -m json.tool

# Test behind proxy
curl -x http://proxy:8080 https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY" | head -20

Environment & Config Errors

# "No module named openclaw" — wrong Python / not in PATH
which python; python --version
which openclaw  # should match same Python environment

# Fix: ensure you're in the right venv
source ~/.venv/openclaw/bin/activate
openclaw --version

# "config.yaml: permission denied"
ls -la ~/.openclaw/
chmod 600 ~/.openclaw/config.yaml  # restrict to owner only

# "API key not found" despite it being set
# Check for invisible characters in the key string:
openclaw config get openai.api_key | cat -A
# Should end with $ not ^M$ (Windows line ending contamination)

Error Code Reference

OpenClaw uses structured error codes for machine-readable output and log filtering. Each code has the pattern CATEGORY_NNN.

Authentication (AUTH)

CodeMessageResolution
AUTH_001API key not foundSet OPENAI_API_KEY or equivalent environment variable
AUTH_002API key invalid or expiredRegenerate the key in your provider's dashboard
AUTH_003Insufficient permissionsYour API key plan doesn't cover this model/feature
AUTH_004Organization quota exceededCheck billing and usage limits on the provider site

Connectivity (CONN)

CodeMessageResolution
CONN_001Connection refusedCheck that the target service is running and the URL is correct
CONN_002Request timeoutIncrease request_timeout in config or check network latency
CONN_003SSL certificate errorUpdate CA certificates or set verify_ssl: false for internal services only
CONN_004Proxy authentication requiredSet HTTP_PROXY and HTTPS_PROXY env vars with credentials

Tool Execution (TOOL)

CodeMessageResolution
TOOL_001Tool not foundPack providing this tool is not installed; run openclaw install --list
TOOL_002Tool execution failedCheck tool logs; often a misconfigured path or missing system dependency
TOOL_003Permission deniedallow_command_exec: true must be set in config for shell tools

Memory & Configuration (MEM/CFG)

CodeDescriptionResolution
MEM_001Context window exceededReduce max_context_tokens in config or split the task
MEM_002Embedding store corruptRun openclaw doctor --repair-memory
CFG_001Config file not foundRun openclaw config init to create a default config
CFG_002YAML parse errorValidate your config.yaml with openclaw config validate
CFG_003Unknown config keyCheck the Configuration reference for valid keys

Platform-Specific Errors

PlatformErrorFix
Windows'openclaw' is not recognizedScripts not on PATH; see Windows installation
WindowsUnicodeDecodeError cp1252Set $env:PYTHONIOENCODING="utf-8" before running
macOSOperation not permittedGrant Terminal full-disk access in System Settings > Privacy & Security
macOSxcrun: invalid developer pathRun xcode-select --install
Linuxexternally-managed-environmentUse a virtual environment; never install to system Python
Linuxlibssl.so.1.1 not foundInstall: sudo apt install libssl-dev or equivalent
← Troubleshooting Overview Debugging →