OpenClaw Manual OpenClaw
Troubleshooting 15 min read

OpenClaw Common Errors and How to Fix Them

Comprehensive guide to diagnosing and fixing common OpenClaw errors including installation issues, API errors, channel problems, and performance issues.

O

OpenClaw Manuals

Tutorial Authors

Quick Diagnostics

Before diving into specific errors, run these diagnostics:

bash 
# Check overall status
openclaw status

# Verify configuration
openclaw config validate

# Check logs for recent errors
openclaw logs --tail 50 --level error

# Run health check
openclaw doctor

Installation Errors

Error: "Node.js version too old"

Error: OpenClaw requires Node.js >= 22.0.0
Current version: 18.17.0

Fix:

bash 
# Using nvm (recommended)
nvm install 22
nvm use 22
nvm alias default 22

# Or using Homebrew (macOS)
brew install node@22

# Verify
node --version  # Should show v22.x.x

Error: "EACCES permission denied"

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

Fix: Don't use sudo. Instead, fix npm permissions:

bash 
# Option 1: Use nvm (recommended)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# Option 2: Change npm's default directory
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

# Then reinstall
npm install -g openclaw@latest

Error: "Cannot find module"

Error: Cannot find module '@openclaw/core'

Fix:

bash 
# Clear npm cache and reinstall
npm cache clean --force
npm uninstall -g openclaw
npm install -g openclaw@latest

# Or use the installer script
curl -fsSL https://openclaw.ai/install.sh | bash

Error: "gyp ERR! build error" (Native modules)

gyp ERR! build error
gyp ERR! stack Error: `make` failed with exit code: 2

Fix: Install build tools:

bash 
# macOS
xcode-select --install

# Ubuntu/Debian
sudo apt install build-essential python3

# Windows
npm install -g windows-build-tools

API and Authentication Errors

Error: "401 Unauthorized"

Error: API request failed with status 401: Invalid API key

Fix:

bash 
# Verify your API key is set
openclaw config get api-key

# If empty or wrong, set it again
openclaw config set api-key

# Check the key format (Anthropic keys start with sk-ant-)
# Make sure there are no extra spaces or quotes

Error: "429 Rate Limited"

Error: Rate limit exceeded. Please retry after 60 seconds.

Fix:

json 
// ~/.openclaw/openclaw.json
{
  "model": {
    "rateLimiting": {
      "retryOnRateLimit": true,
      "maxRetries": 3,
      "retryDelay": 5000,
      "maxRequestsPerMinute": 30
    }
  }
}

For persistent rate limiting, consider upgrading your API tier or using a different model:

bash 
openclaw config set default-model claude-3-5-haiku

Error: "402 Payment Required"

Error: API request failed: Insufficient credits

Fix:

  1. Check your API provider balance
  2. Add credits to your account
  3. Or set up usage limits:
json 
// ~/.openclaw/openclaw.json
{
  "model": {
    "quotas": {
      "daily": {
        "enabled": true,
        "maxTokens": 100000,
        "warningThreshold": 80000
      }
    }
  }
}

Error: "Connection Refused" to API

Error: connect ECONNREFUSED api.anthropic.com:443

Fix:

bash 
# Check internet connection
ping api.anthropic.com

# Check if behind a proxy
echo $HTTP_PROXY
echo $HTTPS_PROXY

# Configure proxy if needed
openclaw config set proxy http://your-proxy:8080

# Or check firewall/VPN settings

Gateway Errors

Error: "EADDRINUSE: Port already in use"

Error: listen EADDRINUSE: address already in use :::18789

Fix:

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

# Kill the process
kill -9 

# Or use a different port
openclaw gateway start --port 18790

# Update config to use new port
openclaw config set gateway-port 18790

Error: "Gateway failed to start"

Error: Gateway failed to start: Cannot read config file

Fix:

bash 
# Validate config file syntax
openclaw config validate

# If corrupted, reset to defaults
openclaw config reset --confirm

# Then reconfigure
openclaw onboard

Error: "Gateway not responding"

bash 
# Check if gateway is running
openclaw status

# If stopped, check why
openclaw logs --tail 100

# Try restarting
openclaw gateway restart

# If still failing, check system resources
free -h  # Memory
df -h    # Disk space

Channel-Specific Errors

WhatsApp: "Session expired"

Error: WhatsApp session invalid or expired

Fix:

bash 
# Re-authenticate
openclaw channel disconnect whatsapp
openclaw channel connect whatsapp
# Scan the new QR code

WhatsApp: "QR code not generating"

bash 
# Check if another session is active
pkill -f "openclaw.*whatsapp"

# Clear old session data
rm -rf ~/.openclaw/whatsapp-session

# Try again
openclaw channel connect whatsapp

Telegram: "Conflict: terminated by other getUpdates"

Error: Conflict: terminated by other getUpdates request

Another instance is using the same bot token.

Fix:

bash 
# Stop all OpenClaw instances
pkill -f openclaw

# Check for other running instances
ps aux | grep openclaw

# Start fresh
openclaw gateway start

Discord: "Invalid token"

Error: An invalid token was provided

Fix:

bash 
# Regenerate token in Discord Developer Portal
# Bot → Reset Token

# Update OpenClaw
openclaw config set discord-token NEW_TOKEN
openclaw gateway restart

Discord: "Missing intents"

Error: Disallowed intents specified

Fix:

  1. Go to Discord Developer Portal
  2. Select your application → Bot
  3. Enable required intents under "Privileged Gateway Intents"
  4. Save and restart OpenClaw

Memory and Performance Errors

Error: "JavaScript heap out of memory"

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

Fix:

bash 
# Increase Node.js memory limit
export NODE_OPTIONS="--max-old-space-size=4096"

# Add to your shell profile for persistence
echo 'export NODE_OPTIONS="--max-old-space-size=4096"' >> ~/.bashrc

# Restart OpenClaw
openclaw gateway restart

Error: "Too many open files"

Error: EMFILE: too many open files

Fix:

bash 
# Check current limit
ulimit -n

# Increase limit (temporary)
ulimit -n 65535

# Increase limit (permanent - Linux)
echo "* soft nofile 65535" | sudo tee -a /etc/security/limits.conf
echo "* hard nofile 65535" | sudo tee -a /etc/security/limits.conf

# macOS
sudo launchctl limit maxfiles 65535 200000

Slow Response Times

Diagnose:

bash 
# Check model latency
openclaw benchmark

# Check system resources
openclaw stats

Fix:

json 
// ~/.openclaw/openclaw.json
{
  "model": {
    "default": "claude-3-5-haiku",
    "streaming": true,
    "maxContextTokens": 4096
  },
  "gateway": {
    "caching": {
      "enabled": true,
      "ttl": 300
    }
  }
}

Configuration Errors

Error: "Invalid YAML syntax"

Error: Config file has invalid YAML syntax at line 15

Fix:

bash 
# Validate YAML
openclaw config validate

# Common issues:
# - Tabs instead of spaces (use 2 spaces)
# - Missing colons after keys
# - Unquoted special characters

# Fix or reset
openclaw config edit
# or
openclaw config reset --confirm

Error: "Unknown configuration key"

Warning: Unknown configuration key 'gateway.unknownOption'

Fix:

bash 
# Check available options
openclaw config list

# Remove unknown keys
openclaw config edit

Error: "Environment variable not set"

Error: Required environment variable ANTHROPIC_API_KEY is not set

Fix:

bash 
# Add to .env file
echo "ANTHROPIC_API_KEY=sk-ant-xxxxx" >> ~/.openclaw/.env

# Or export in shell
export ANTHROPIC_API_KEY=sk-ant-xxxxx

# Add to shell profile for persistence
echo 'export ANTHROPIC_API_KEY=sk-ant-xxxxx' >> ~/.bashrc

Database and Storage Errors

Error: "Database locked"

Error: SQLITE_BUSY: database is locked

Fix:

bash 
# Stop OpenClaw
openclaw gateway stop

# Check for lock files
ls -la ~/.openclaw/*.lock

# Remove stale locks
rm ~/.openclaw/*.lock

# Restart
openclaw gateway start

Error: "Disk quota exceeded"

Error: ENOSPC: no space left on device

Fix:

bash 
# Check disk usage
df -h

# Clear OpenClaw logs and cache
openclaw cache clear
openclaw logs clear --older-than 7d

# Clear old sessions
rm -rf ~/.openclaw/sessions/*.old

Getting More Help

Enable Debug Logging

bash 
# Set debug mode
export OPENCLAW_DEBUG=true
openclaw gateway start

# Or in config
openclaw config set logLevel debug

Generate Diagnostic Report

bash 
openclaw doctor --report > diagnostic-report.txt

Community Support

Filing a Bug Report

When reporting issues, include:

bash 
# System info
openclaw --version
node --version
uname -a

# Configuration (redact sensitive data)
openclaw config show --redact

# Recent logs
openclaw logs --tail 100

Next Steps