OpenClaw Troubleshooting: Fix Common Errors, Crashes & API Issues

💡 New! Error Dictionary Available We now have detailed step-by-step fix guides for each error! 👉 Check the Error Dictionary for in-depth solutions with verification steps.

Stuck with an error? Use Ctrl+F (or Cmd+F) to search for your specific error code on this page, or jump directly to a detailed fix guide below.

🛑 Installation Errors (npm install)

The most common issues happen during the initial setup.

1. gyp: No Xcode or CLT version detected

Symptoms:

• Installation fails while building better-sqlite3 or sharp.
• Error log contains: node-gyp rebuild failed.
• Error log contains: python: not found.

Solution (Mac):

Your Mac is missing the build tools required to compile native modules.

xcode-select --install

If that doesn't work, verify Python is installed:

python3 --version

Solution (Windows):

You need Windows Build Tools. Run this in PowerShell as Administrator:

npm install --global --production windows-build-tools

👉 Full Guide: Fix gyp/Xcode Build Errors →

2. EACCES: permission denied

Symptoms:

• Error: EACCES: permission denied, mkdir ...
• You are trying to run npm install without permissions.

Solution:

⚠️ Never use sudo npm install. It causes more permission issues later.

Instead, fix your npm permissions globally or use a version manager like nvm (recommended).

Quick Fix:

# Change ownership of your npm directories
sudo chown -R $USER:$(id -gn $USER) ~/.config
sudo chown -R $USER:$(id -gn $USER) ~/.npm

👉 Full Guide: Fix EACCES Permission Errors →

3. npm ERR! code ERESOLVE (Dependency Conflict)

Symptoms:

• npm ERR! code ERESOLVE
• npm ERR! ERESOLVE could not resolve

Solution:

This happens when dependency versions conflict. Force npm to ignore strict peer dependencies:

npm install --legacy-peer-deps

👉 Full Guide: Fix ERESOLVE Dependency Conflicts →

🔌 Runtime Errors (npm start)

1. Port 3000 Already in Use (EADDRINUSE)

Symptoms:

• Error: listen EADDRINUSE: address already in use :::3000
• OpenClaw crashes immediately after starting.

Solution A: Kill the blocking process

Mac/Linux:

lsof -i :3000
# Take note of the PID (e.g., 12345)
kill -9 <PID>

Windows (PowerShell):

netstat -ano | findstr :3000
taskkill /PID <PID> /F

Solution B: Change the Port

You don't have to use port 3000. Start OpenClaw on port 3001 or 8080:

# Linux/Mac
PORT=3001 npm run start

# Windows (PowerShell)
$env:PORT="3001"; npm run start

👉 Full Guide: Fix Port 3000 In Use →

2. Module Not Found / Crashes

Symptoms:

• Error: Cannot find module 'sharp'
• Error: Cannot find module 'better-sqlite3'

Solution:

This usually means a binary failed to download or compile.

# 1. Delete existing modules
rm -rf node_modules package-lock.json

# 2. Reinstall (try specifically for your architecture)
npm install --platform=darwin --arch=arm64 sharp  # For Apple Silicon
npm install

👉 Full Guide: Fix Module Not Found Errors →

🔑 API Key & Connectivity Issues

1. 401 Unauthorized / Invalid Key

Symptoms:

• Error: Invalid API key
• Bot replies with empty messages or "I cannot help with that".

Solution:

Check for Spaces: A very common mistake is pasting the key with a space at the end.

# ❌ WRONG
OPENAI_API_KEY=sk-123456   

# ✅ CORRECT
OPENAI_API_KEY=sk-123456

Restart Required: If you edited .env, you must stop (Ctrl+C) and restart the server (npm run start) for changes to apply.

👉 Full Guide: Fix Invalid API Key Errors →

2. 429 Too Many Requests (Insufficient Quota)

Symptoms:

• Error: 429 You exceeded your current quota
• Error: Insufficient funds

Solution:

This is not a bug in OpenClaw.

• OpenAI: Check your billing dashboard. Do you have credits? (Trial credits expire).
• Anthropic: You must add a credit card and pre-load at least $5 to use the API via code, even if the web chat is free.

👉 Full Guide: Fix 429 Quota Exceeded Errors →

🪟 Windows (WSL2) Specific Issues

1. Can't Access localhost:3000

Symptoms:

• OpenClaw says "Server running on port 3000".
• Browser shows "This site can't be reached".

Solution:

WSL2 sometimes doesn't map localhost correctly.

1. Try accessing via IP: http://127.0.0.1:3000
2. Find your WSL IP address:

hostname -I

1. Use that IP in your browser (e.g., http://172.x.x.x:3000).

👉 Full Guide: Fix WSL2 Localhost Issues →

🐛 Still Stuck? How to View Logs

If your error isn't listed here, you need to see the full crash log.

1. Check the Terminal: Scroll up in the window where you ran npm start.
2. Check the Browser Console:
   • Right-click the webpage → Inspect.
   • Go to the Console tab.
   • Screenshot any red errors and search specifically for those lines.

Need more help?

Try searching the Official GitHub Issues with your specific error message.