Common errors and how to fix them. Find your error, get the fix, get back to building.
Run these commands in order to diagnose most issues:
docker compose ps
See if OpenClaw is running or in a restart loop
docker compose logs openclaw --tail 50
Look for error messages in the last 50 lines
docker compose exec openclaw printenv | grep -E 'API_KEY|TOKEN'
Confirm your API keys and tokens are set correctly
curl -I http://localhost:3000
Check if OpenClaw responds on the local port
docker compose down && docker compose up -d
Clean restart when configuration changed
| Scenario | Action |
|---|---|
| Changed .env file | Restart |
| Updated docker-compose.yml | Restart |
| API key quota exceeded | Reconfigure |
| WhatsApp QR expired | Restart |
| Port already in use | Reconfigure |
| Container keeps restarting | Reconfigure |
| Gateway token invalid | Reconfigure |
| Out of memory (OOM) | Reconfigure |
| Code | Meaning | Quick Fix |
|---|---|---|
ECONNREFUSED | Connection refused | Check if the service is running and the port is correct |
EADDRINUSE | Port already in use | Kill the process using the port or change ports |
ENOENT | File or directory not found | Check file paths in your configuration |
EPERM | Permission denied | Check file permissions or run with appropriate privileges |
ETIMEDOUT | Connection timed out | Check network/firewall or increase timeout settings |
401 | Unauthorized | Verify API keys and tokens are correct |
403 | Forbidden | Check API permissions and quota limits |
429 | Rate limited | Wait and retry, or upgrade your API tier |
500 | Internal server error | Check logs for details, may be a bug |
502 | Bad gateway | Upstream service unavailable, check network |
503 | Service unavailable | Service overloaded or down, retry later |
OpenClaw requires Docker to run. This error means your system can't connect to the Docker engine — either it's not installed, not started, or your user doesn't have access.
Fix it →ErrorDocker requires special permissions to run. If your Linux user isn't in the 'docker' group, every Docker command will fail with a permission error unless you use sudo.
Fix it →ErrorIf the OpenClaw container crashes on startup and Docker's restart policy keeps bringing it back, you'll see it cycling between 'restarting' and 'running'. The root cause is usually a configuration problem.
Fix it →OpenClaw's web interface runs on port 3000 by default. If another process or a previous OpenClaw container is already using that port, the new container will fail to start.
Fix it →WarningOpenClaw is running but you can't reach it in your browser. This is almost always a firewall or networking issue — the container is fine, but traffic can't get through.
Fix it →OpenClaw uses a gateway token to authenticate API requests. This error means the token in your environment doesn't match what the server expects — usually a copy-paste issue or a regenerated token.
Fix it →ErrorOpenClaw uses the OpenAI API (or other LLM providers) for AI responses. If your API key is wrong, expired, or has no credits, all AI features will fail.
Fix it →