OpenClaw Error Codes & Common Stack Traces Explained
Companion: Full reference table at error code reference. This page optimizes for pasted search queries.
Config validation failed
Meaning: YAML/schema mismatch or missing required keys.
Fix: openclaw config validate → read line numbers → compare with file structure. Common after upgrades (migration).
Gateway EADDRINUSE / port in use
Meaning: Another process holds the gateway port (default 18789).
Fix: openclaw status; stop duplicate daemon; see gateway issues.
Channel webhook / token errors
Meaning: Invalid bot token, expired QR (WhatsApp), or firewall blocking webhooks.
Fix: Channel-specific steps in channels guide and channel setup.
Model API 401 / 429
Meaning: Bad API key or rate limit.
Fix: Rotate keys (credentials); switch model tier (LLM guide); details in model troubleshooting.
Memory / session corruption
Meaning: Unwritable path or partial upgrade.
Fix: Memory troubleshooting; restore backup if needed.
Universal first steps
openclaw doctor
openclaw doctor --fix
openclaw logs --tail 50More: quick diagnostics.