Troubleshoot — OpenClaw Error Index
Search for your exact error message. Each page shows the error text, what causes it, and the copy-paste fix.
OpenClaw guide · Updated 2026 · 20 common errors
Quick Fix
Before diving into specific errors, run the universal diagnostic:
openclaw doctor --deep --yes
This auto-fixes 80% of issues. If it doesn't solve your problem, find your error below.
All Errors
Gateway & Startup
- Error: listen EADDRINUSE :::18789 — Port 18789 Already in Use
- Error: connect ECONNREFUSED 127.0.0.1:18789 — Gateway Not Running
- Gateway crashed / restart loop — Gateway Keeps Crashing
- openclaw: command not found — Binary Not in PATH
- Node.js 22+ required — Node.js Version Too Old
- Config validation failed — Invalid Config / Unrecognized Key
- ENOSPC: no space left on device — Disk Space Full
Authentication & API
- 401 Unauthorized / Invalid API key — API Key Issues
- 429 Too Many Requests — Rate Limit Exceeded
- Pairing required / disconnected 1008 — Pairing Not Completed
Channels
- WhatsApp QR expired / Connection dropped — WhatsApp QR Issues
- WhatsApp connected but not responding — WhatsApp Silent
- Telegram 401 / Invalid bot token — Telegram Token Invalid
Tools & Sandbox
- EACCES / sandbox: command blocked — Sandbox Permission Denied
- Agent replies but never runs tools — Tools Disabled
- Docker socket permission denied — Docker Access Denied
Memory & Context
- Context length exceeded — Token Limit Hit
- Agent forgets everything — Memory Not Persisting
Scheduled Tasks
- Cron job didn't run / heartbeat skipped — Cron/Heartbeat Issues
Network & SSL
- WebSocket connection failed / HTTPS required — SSL/TLS Error
Still Stuck?
# Full diagnostic
openclaw doctor --deep --yes
# Live logs while reproducing the issue
openclaw logs --follow
# Deep status check
openclaw status --all --deep
If your error isn't listed here, check the full cheatsheet troubleshooting section or ask in the OpenClaw Discord.