Fix Any OpenClaw Error
Find your error below, or paste it into the Error Doctor for instant diagnosis.
Paste your full error message into the Error Doctor — it fuzzy-matches against 30+ known issues and gives you the exact fix commands.
Open Error DoctorAll Troubleshooting Guides
Device Token Mismatch
Fix "disconnected (1008): unauthorized: device token mismatch". Rotate tokens, kill zombie processes.
disconnected (1008): unauthorized: device token mismatchWindows Gateway Errors
Full Windows troubleshooting: npm install failures, zombie processes, port conflicts, crash loops.
PSSecurityException / EBUSY / spawn docker ENOENTConnection Refused (ECONNREFUSED)
Agent not responding on localhost:3000. Fix IPv4/IPv6 binding and port issues.
ECONNREFUSED 127.0.0.1:3000JSON Parse Errors
Fix trailing commas, unescaped backslashes, and invalid JSON in config files.
SyntaxError: Unexpected tokenAPI Key Problems (401 / 429 / 404)
Invalid key, rate limits exceeded, or model not found. Debug provider authentication.
401 Unauthorized / 429 Rate LimitDocker macOS Errors
EACCES permission denied, token mismatch in containers, Chrome not found in Docker.
EACCES: permission denied, mkdir '/Users'Ollama 5-Minute Timeout
Generation cuts at exactly 300 seconds. Fix the undici headersTimeout and retry loop.
UND_ERR_HEADERS_TIMEOUT / 500 error at 5m0sMessage Ordering Conflict
Bot goes silent or shows "Message ordering conflict". Fix unsupported developer role.
Message ordering conflict / ROLE_UNSPECIFIEDspawn git ENOENT
Git not installed or not in PATH. One-command fix for Windows, macOS, and Linux.
npm error syscall spawn git / ENOENTPowerShell Scripts Blocked
Fix PSSecurityException "running scripts is disabled". Use npm.cmd or set execution policy.
npm.ps1 cannot be loaded because running scripts is disabledWindows Basics (Paths & Firewall)
Path escaping, firewall rules, Node.js PATH issues, and Docker WSL2 setup.
Windows path / firewall / Node.js not foundBrowser Control Service Timeout
Fix "Can't reach browser control service (timed out after 20000ms)". Hung CDP, stray Chromium, port 18800 conflicts.
Can't reach the openclaw browser control serviceGateway Lock Timeout
Fix "gateway already running; lock timeout". Stale lock files in Docker, PID reuse, manual cleanup.
gateway already running (pid NNN); lock timeout after 5000msPairing Required (1008)
Fix "disconnected (1008): pairing required". Approve devices, fix Docker NAT, configure LAN access.
disconnected (1008): pairing requiredGateway Token Mismatch
Fix "gateway token mismatch (set gateway.remote.token to match gateway.auth.token)". Docker, remote CLI, env var override.
unauthorized: gateway token mismatchDevice Identity Required (1008)
Fix "device identity required". LAN access needs HTTPS or token URL. Secure context requirement for Control UI.
disconnected (1008): device identity requiredspawn docker ENOENT
Docker not installed or not in PATH. Install Docker or disable sandbox mode to fix immediately.
spawn docker ENOENT / agent failed before replyError Not Listed?
Paste your error into the Doctor tool or search existing GitHub issues.