Error Code Reference

🔧 Error code lookup: Use this page to find OpenClaw error messages and codes, with causes and step-by-step solutions. For a full diagnostic flow, start with Quick diagnostics or the main Troubleshooting Guide.

Quick diagnostic

Not sure which error you have? Run openclaw doctor first. It checks configuration, gateway, paths, and common issues. Many errors will be reported there with hints.

# Full health check (recommended first step)
openclaw doctor

# Try auto-fixing some issues
openclaw doctor --fix

# Check gateway and config in use
openclaw status

# Validate configuration file
openclaw config validate

# View recent logs (errors often show codes or messages here)
openclaw logs --tail 50
openclaw logs --follow

See Quick diagnostics and Troubleshooting Guide for the full flow. If the gateway won’t start, see Gateway Issues.

Error codes and messages by category

Errors are grouped by where they occur. Click the category or error for more detail and links to dedicated troubleshooting pages.

Installation & setup errors

These occur during or right after installation. For full steps, see Installation Errors.

Error / message Likely cause Solution
openclaw: command not found CLI not on PATH or not installed Ensure Node.js 22+ and OpenClaw are installed; add install directory to PATH, or use full path. See Installation Errors and Installation Guide.
Node version / Unsupported engine Node.js < 22 Upgrade to Node.js 22 or newer. Check with node -v.
Permission denied (EACCES) Insufficient permissions for install or config directory Fix ownership or run installer with appropriate permissions; avoid sudo for global npm if possible. See Installation Errors.
npm install / install script failed Network, dependency, or platform issue Retry; check network and Node/npm versions; use official installer script from official docs when available.

Gateway errors

Errors related to the OpenClaw gateway daemon. For full steps, see Gateway Issues.

Error / message Likely cause Solution
Gateway won't start Port in use, config invalid, or binding issue Free port (e.g. 1618); run openclaw doctor; ensure gateway binds to 127.0.0.1. See Gateway Issues and Security Best Practices.
Address already in use / EADDRINUSE Another process using gateway port Find process with lsof -i :1618 (or your port); stop it or change port in config.
Gateway unauthorized / can't connect CLI and gateway token or config mismatch Ensure single config path for CLI and gateway; run openclaw doctor; restart gateway. See Gateway Issues.
RPC probe failure / Token mismatch Gateway token changed or wrong config Restart gateway so CLI and gateway share same token; verify config path with openclaw doctor.
Gateway already running (PID lock) Previous instance still running or stale PID file Stop existing process or remove stale PID file; then start again. See Gateway Issues.

Channel connection errors

Errors when connecting to WhatsApp, Telegram, Discord, Slack, etc. For full steps, see Channel Errors.

Error / message Likely cause Solution
Telegram bot not responding Wrong token, gateway down, or channel disabled Verify token from BotFather; run openclaw status and openclaw doctor; see Channel Errors and Telegram setup.
WhatsApp connection failed Credentials or channel config Check channel block and credentials; run openclaw config validate and openclaw doctor. See Channel Errors.
Discord permission errors Bot permissions or OAuth scope Re-invite bot with correct permissions; check Discord developer portal and channel config. See Discord setup.
Channel schema unavailable / unsupported Adapter name or schema changed for your OpenClaw version Update config to match your version; check official docs and Configuration Problems.

Configuration errors

Config file validation, paths, and schema. For full detail, see Configuration Problems.

Error / message Likely cause Solution
Config validation failed / Invalid configuration Invalid YAML, wrong keys, or schema mismatch Run openclaw config validate and openclaw doctor; fix reported key or syntax; check config file structure. See Config validation failed.
Session file path violations Session path not allowed or bad permissions Set valid session path in config; ensure directory exists and is writable. See Session path violations.
Model not allowed Agent references a model not in provider config or allowlist Add model to provider config and/or allowlist; verify agent model matches a configured provider. See model provider setup and Model not allowed.
Missing scope errors Config node or permission scope missing Add required scope or config block per official docs; run openclaw config validate.
Schema node unsupported Config structure doesn’t match your OpenClaw version Update config to match version schema; check release notes and config file structure. See Schema node unsupported.
Agent config moved / agent not found CLI and gateway using different config path Use single config path for both; verify with openclaw doctor. See Agent config moved.

Model & API errors

Errors from LLM providers (Anthropic, OpenAI, etc.). For full steps, see Model & API Errors.

Error / message Likely cause Solution
Rate limit exceeded / 429 Too many requests to provider Wait and retry; reduce concurrency; consider usage limits in provider dashboard. See Model & API Errors.
Billing error / insufficient quota API key out of credits or payment issue Check provider billing and quota; add payment method or switch key. See model provider setup.
API key invalid / 401 Unauthorized Wrong or expired API key Verify key in config or environment; ensure no extra spaces; rotate key if compromised. See Credential Management.
All models failed / Provider unreachable Network or provider outage; misconfigured provider Check network and firewall; verify provider URL and key; check provider status page. See Model & API Errors.
Model timeout Slow response from LLM Increase timeout in config if needed; check provider latency; try another model or region.

Skills & marketplace errors

Errors when installing or loading skills from ClawHub or local skills. For full steps, see Skills Issues.

Error / message Likely cause Solution
Skill installation failed Network, name, or version issue Retry; check skill name and version; ensure gateway can reach ClawHub. See Skills Issues and Skills marketplace.
Skill won't load / load error Missing dependency, wrong path, or broken skill Check skill path in config; run openclaw logs --tail 50 for load errors; reinstall or update skill. See Installing skills.
Credential leak in skill (security audit) Skill may expose or misuse credentials Run openclaw security audit; remove or replace risky skills; see Skills security and Skills security audit.

Performance & resource errors

High memory, slow responses, or crashes. For full steps, see Performance Problems.

Error / message Likely cause Solution
High memory usage / OOM Insufficient RAM or memory leak Upgrade to 4GB+ RAM if possible; reduce concurrency or model count; check for skill leaks. See Performance Problems.
Slow response times Network, model latency, or overload Check provider latency; reduce load; consider faster model or region. See Performance Problems.
Gateway crashes / Connection timeout Resource exhaustion or network/firewall Check logs; ensure firewall allows traffic; bind to 127.0.0.1 and use tunnel for remote access. See Gateway Issues and Network isolation.

Step-by-step debugging

  1. Run health check: openclaw doctor and optionally openclaw doctor --fix.
  2. Check status: openclaw status to see gateway and config in use.
  3. Review logs: openclaw logs --tail 50 or openclaw logs --follow for the exact error message or code.
  4. Validate config: openclaw config validate for config-related errors.
  5. Match error to category above: Use the tables on this page to find the solution and linked guide.

Getting help

If you're still stuck: