← Back to blog

OpenClaw Errors: Every Common Error and How to Fix It

| Weihao Ming

If you’ve self-hosted OpenClaw, you’ve seen at least three of these errors. This post covers every common OpenClaw error code, what causes it, and how to fix it — from installation problems and API rate limits to Docker crashes and Telegram webhook failures.

Last week I wiped my VPS and did a clean OpenClaw install. Node was the wrong version, Docker pulled the wrong architecture, and my Telegram webhook refused to connect because I forgot to set up SSL. Three errors in fifteen minutes. I’ve been running OpenClaw Cloud for months and I still trip over this stuff when I go back to self-hosting.

So I wrote down every error I’ve hit, every error users have asked me about, and every error I’ve seen in forums and Discord. Twelve of them. Here they all are.

Installation errors

These hit you before OpenClaw even starts.

1. “Cannot find module ‘openclaw’”

You’ll see this right after running npx openclaw or trying to import it:

Error: Cannot find module 'openclaw'

Cause: Almost always a Node.js version problem. OpenClaw requires Node.js 22 or newer. If you’re on Node 18 or 20, the install might appear to succeed but the module resolution will fail silently.

Fix:

node --version
# If it's below v22, upgrade:
nvm install 22
nvm use 22

If your Node version is fine, check your PATH. On some Linux distros, global npm packages end up in a directory that isn’t in your shell’s PATH. Run npm root -g and make sure that directory is accessible.

2. “EADDRINUSE :::3000”

Error: listen EADDRINUSE :::3000

Cause: Something else is already running on port 3000. Could be another OpenClaw instance, a dev server, or anything else.

Fix:

# Find what's using the port
lsof -i :3000

# Kill it
kill -9 <PID>

Or just change the port in your OpenClaw config:

PORT=3001 npx openclaw

3. “EACCES: permission denied”

npm ERR! Error: EACCES: permission denied, mkdir '/usr/local/lib/node_modules'

Cause: You’re installing global npm packages without permission. Do not fix this with sudo npm install.

Fix: Configure npm to use a directory you own:

mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

Then reinstall OpenClaw without sudo.

4. Docker “no matching manifest for linux/arm64”

no matching manifest for linux/arm64/v8 in the manifest list entries

Cause: You’re running Docker on an ARM machine (Apple Silicon Mac, Raspberry Pi, some ARM VPS instances) and the OpenClaw Docker image doesn’t have an ARM build — or you’ve pinned a tag that’s x86-only.

Fix:

# Force x86 emulation
docker run --platform linux/amd64 openclaw/openclaw:latest

This uses QEMU emulation under the hood. It’s slower, but it works. If performance matters, run OpenClaw natively with Node.js instead of Docker on ARM.

5. Docker container exits immediately

You start the container and it just… stops. docker ps shows nothing. docker ps -a shows it exited with code 1.

docker logs <container_id>
# Usually shows: "Error: Missing required environment variable: ..."

Cause: OpenClaw needs certain environment variables to start — at minimum an API key for your chosen provider. Without them, it exits immediately.

Fix: Make sure you’re passing your env vars:

docker run -d \
  -e ANTHROPIC_API_KEY=sk-ant-... \
  -e TELEGRAM_BOT_TOKEN=... \
  -p 3000:3000 \
  openclaw/openclaw:latest

Or use a .env file:

docker run -d --env-file .env -p 3000:3000 openclaw/openclaw:latest

Check the Docker setup guide for the full list of required variables.

Runtime errors

These show up after OpenClaw is installed and running.

6. “Invalid API key” / “401 Unauthorized”

Error: 401 Unauthorized - Invalid API key

Cause: Your API key is wrong, expired, or for the wrong provider.

Common gotchas:

  • Anthropic keys start with sk-ant-. If yours doesn’t, it’s not an Anthropic key.
  • OpenAI keys require a payment method on file. A key from a free-tier account with no billing set up will return 401 even though the key itself is valid.
  • Keys can expire or get revoked. If it worked yesterday and doesn’t today, regenerate it in your provider’s dashboard.

Fix: Double-check the key. Paste it into the provider’s API playground to verify it works independently of OpenClaw. Then update your config.

If you’re using OpenClaw Cloud, you bring your own key (BYOK) but the setup wizard validates it before saving — so you’ll never hit this at runtime.

7. “Rate limit exceeded” / “429 Too Many Requests”

Error: 429 Too Many Requests - Rate limit exceeded

This is the most frustrating error because it’s not your fault and you can’t really fix it by changing code.

Cause: Your API provider is throttling you. Every provider has rate limits based on your usage tier:

Anthropic tiers:

  • Tier 1 (new accounts): ~60 requests/minute
  • Tier 2: ~300 requests/minute
  • Tier 3: ~1,000 requests/minute
  • Higher tiers require spending history and sometimes manual approval

OpenAI tiers:

  • Free: 3 RPM (basically unusable for an agent)
  • Tier 1 ($5+ spent): 60 RPM
  • Tier 2 ($50+ spent): 500 RPM

If OpenClaw is running multi-step tasks — browsing, executing terminal commands, reading files — it can burn through dozens of API calls in a single task. Hit a rate limit mid-task and the whole thing fails.

Fix:

  1. Check your tier. Log into your provider’s dashboard and see where you stand.
  2. Add retry logic. OpenClaw has built-in retry settings — make sure exponential backoff is enabled.
  3. Switch models for simple tasks. Use a fast, cheap model (Groq, Ollama) for simple operations and save Claude/GPT-4 for complex reasoning.
  4. Request a tier upgrade. Anthropic and OpenAI both let you request higher limits.

OpenClaw Cloud handles this automatically with managed retries, smart backoff, and request queuing. No 429s leaking through to your tasks. That alone is worth it if you’re running OpenClaw for anything production-adjacent.

8. “Connection refused” / “ECONNREFUSED”

Error: connect ECONNREFUSED 127.0.0.1:11434

Cause: OpenClaw is trying to reach a service — usually a local model via Ollama, or an API endpoint — and can’t connect.

Common causes:

  • Ollama isn’t running (ollama serve)
  • You’re inside Docker trying to reach localhost (which is the container, not your host)
  • Firewall blocking outbound connections to API providers

Fix:

If it’s a Docker networking issue:

# Use host.docker.internal instead of localhost
OLLAMA_HOST=http://host.docker.internal:11434

If it’s a firewall issue, make sure ports 443 (HTTPS to API providers) and any local service ports are open. Check our Ollama integration guide for the full Docker + Ollama setup.

9. Telegram webhook failed / bot not responding

Your OpenClaw instance is running, but your Telegram bot just… doesn’t respond. No errors in the OpenClaw logs either.

Cause: Telegram requires HTTPS for webhooks. If your server doesn’t have a valid SSL certificate, Telegram silently refuses to deliver messages to your bot.

Fix: Use Caddy as a reverse proxy. It handles SSL automatically:

# Caddyfile
yourdomain.com {
    reverse_proxy localhost:3000
}
sudo caddy start

That’s it. Caddy gets a Let’s Encrypt certificate automatically. Then set your webhook:

curl -X POST "https://api.telegram.org/bot<TOKEN>/setWebhook" \
  -d "url=https://yourdomain.com/webhook/telegram"

Read more about the Telegram setup in our OpenClaw on Telegram guide.

10. “ENOMEM: not enough memory”

FATAL ERROR: CALL_AND_RETRY_LAST Allocation failed - JavaScript heap out of memory

Or the even more cryptic OOM killer:

Killed

Cause: Your VPS doesn’t have enough RAM. OpenClaw itself is lightweight, but the moment you add a browser (Chromium) and a language model context, memory usage spikes. A $5/mo VPS with 1GB RAM will not survive.

Fix:

  1. Get a VPS with 4GB+ RAM. This is the real fix.
  2. Add swap space as a temporary band-aid:
sudo fallocate -l 4G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab
  1. Increase Node.js heap limit:
NODE_OPTIONS="--max-old-space-size=4096" npx openclaw

But honestly, if you’re hitting memory limits, your VPS is too small. Swap will keep it alive but everything will be slow. For more on VPS sizing, see our self-hosting vs. cloud comparison.

11. “Browser launch failed” / Chromium crash

Error: Failed to launch the browser process!
/root/.cache/puppeteer/chrome/linux-xxx/chrome-linux64/chrome:
error while loading shared libraries: libnss3.so: cannot open shared object file

Cause: OpenClaw’s browser feature uses Chromium under the hood. Minimal VPS images (especially Alpine-based or stripped-down Ubuntu) are missing the system libraries that Chromium needs.

Fix:

On Ubuntu/Debian:

sudo apt-get update && sudo apt-get install -y \
  libnss3 libatk1.0-0 libatk-bridge2.0-0 libcups2 \
  libdrm2 libxkbcommon0 libxcomposite1 libxdamage1 \
  libxrandr2 libgbm1 libpango-1.0-0 libasound2

If you’re running inside Docker, make sure your Dockerfile or image includes these dependencies. The official OpenClaw Docker image should have them, but if you’re building a custom image, you’ll need to add them yourself.

You can also check if the browser feature is something you actually need. If your tasks don’t require web browsing, you can disable it and save yourself the headache.

12. “Task timed out” / agent stops mid-task

OpenClaw starts a task, works on it for a while, then just stops. No crash, no error — it just gives up.

Cause: Usually one of two things:

  1. Context window exhaustion. Every AI model has a maximum context length. If a task generates too much output (long terminal logs, large file contents, extensive browsing data), the context fills up and OpenClaw can’t continue.
  2. API timeout. Long-running model calls can time out, especially with slower providers or during peak hours.

Fix:

  • Break large tasks into smaller steps. Instead of “research this topic and write a 5,000-word article,” do it in stages.
  • Use models with larger context windows (Claude has 200K tokens, which helps).
  • Set appropriate timeout values in your OpenClaw config.
  • Check the memory and context guide for strategies on managing long conversations.

The pattern

Look at that list again. How many of those errors are actually OpenClaw’s fault?

Maybe one. The rest are Node.js version issues, Docker quirks, missing system libraries, API provider rate limits, SSL certificates, VPS memory constraints, and firewall rules. Infrastructure problems. Every single one.

This is the tax of self-hosting. You get full control, full privacy, full flexibility — and in exchange, you become your own DevOps team. Every error on this list is a solvable problem. But solving twelve of them before your AI agent can reliably do its job is a lot of time spent not using the thing you set it up for.

That’s why we built OpenClaw Cloud. Docker, SSL, memory, rate limit handling, browser dependencies, Telegram webhooks — all managed. You bring your API key, pick a model, and start sending messages. No errors to debug because the infrastructure isn’t your problem anymore.

But if you prefer self-hosting — and many people do for good reasons — bookmark this page. You’ll probably need it.

← Back to blog