OpenClaw Common Errors and Solutions (2026, Continuously Updated)

Before Troubleshooting: Check the Logs

Most issues leave clear error messages in the logs. Always start here:

# View recent logs
pnpm openclaw logs --tail

# View logs for a specific component
pnpm openclaw gateway logs
pnpm openclaw channels telegram logs

# Check system status
pnpm openclaw gateway status
pnpm openclaw models list

Category 1: Installation Errors

"node: command not found" or "npm: command not found"

Cause: Node.js is not installed or not in PATH.

Solution:

# Install via nvm (recommended)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
source ~/.bashrc
nvm install 22
nvm use 22

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

"pnpm: command not found"

Solution:

npm install -g pnpm
source ~/.bashrc
pnpm -v  # Should show version number

"pnpm install" fails with ENOENT or EACCES

Cause: Permission issues or missing directories.

Solution:

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

"ENOTFOUND" during install (can't reach npm registry)

Cause: Network issue reaching the npm registry (common in China).

Solution:

# Switch to Taobao mirror
pnpm config set registry https://registry.npmmirror.com
pnpm install

Category 2: Gateway Errors

Gateway fails to start: "port already in use"

Cause: Another process is using port 18789.

Solution:

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

# Kill the process (replace PID with the actual PID)
kill -9 PID

# Or change OpenClaw's port in openclaw.json:
# "gateway": { "port": 18790 }

"Unable to acquire lock" error

Cause: A previous OpenClaw process didn't exit cleanly.

Solution:

# Remove the lock file
rm -f ~/.openclaw/.next/dev/lock

# Or kill all OpenClaw processes
pkill -f "openclaw"
pnpm openclaw gateway start

Gateway starts but WebChat shows "Connection refused"

Cause: Firewall blocking the port, or gateway only listening on localhost.

Solution:

# Open the port in UFW
sudo ufw allow 18789/tcp

# Verify gateway is listening on the right interface
ss -tlnp | grep 18789
# Should show 0.0.0.0:18789, not 127.0.0.1:18789

# If only on localhost, update openclaw.json:
# "gateway": { "host": "0.0.0.0" }

Category 3: Model Configuration Errors

"API Key not set" or "Missing required environment variable"

Solution:

# Check the variable is set
printenv | grep API_KEY

# If missing, add to your .env file
echo 'MINIMAX_API_KEY=sk-your-key' >> ~/.openclaw/.env

# Reload environment
source ~/.openclaw/.env
pnpm openclaw gateway restart

"401 Unauthorized" from the model API

Cause: Invalid or expired API Key.

Solution:

1. Log in to the model provider's console (platform.minimax.io, console.anthropic.com, etc.)
2. Verify the key is active and hasn't been deleted
3. Create a new key if needed
4. Update your .env file and restart OpenClaw

"429 Too Many Requests" / Rate Limit

Cause: You've exceeded the API rate limit or free-tier quota.

Solution:

// Add a fallback model in openclaw.json
{
  "agents": {
    "defaults": {
      "model": {
        "primary": "minimax/MiniMax-M2.1",
        "fallback": ["ollama/llama3.3", "deepseek/deepseek-v3"]
      }
    }
  }
}

"Model not found" or "Unknown model ID"

Cause: Incorrect model ID in config.

Solution: Check the exact model ID in the provider's documentation. Common correct IDs (2026):

• MiniMax: MiniMax-M2.1 (not minimax-m2.1)
• Anthropic: claude-sonnet-4-6 (not claude-sonnet)
• OpenAI: gpt-4o (not gpt4o)

Category 4: Skills Errors

Skill installs but doesn't appear in conversation

Cause: Skill not activated or requires restart.

Solution:

# List installed skills
pnpm openclaw skills list

# Activate a specific skill
pnpm openclaw skills activate skill-name

# Restart gateway
pnpm openclaw gateway restart

"Skill execution failed" error

Cause: Skill has a bug, missing dependency, or incorrect configuration.

Solution:

# Check skill-specific logs
pnpm openclaw skills logs skill-name

# Reinstall the skill
pnpm openclaw skills uninstall skill-name
pnpm openclaw skills install skill-name

Skill uses wrong model

Cause: Skill doesn't have a model specified and is using a default that doesn't meet its requirements.

Solution: Specify the model for the skill in openclaw.json:

{
  "skills": {
    "image-analyzer": {
      "model": "minimax/MiniMax-VL-01"
    }
  }
}

Category 5: Telegram Errors

Bot doesn't respond to messages

Checklist:

# 1. Is the gateway running?
pnpm openclaw gateway status

# 2. Is the Telegram channel enabled?
pnpm openclaw channels list

# 3. Is the webhook configured?
pnpm openclaw channels telegram webhook status

# 4. Re-setup the webhook
pnpm openclaw channels telegram setup-webhook

"Webhook SSL certificate error"

Cause: Telegram requires HTTPS for webhooks. HTTP is rejected.

Solution: Set up a TLS certificate for your domain using Caddy or Certbot:

# Using Caddy (easiest — handles HTTPS automatically)
sudo apt install caddy

# In /etc/caddy/Caddyfile:
# your-domain.com {
#   reverse_proxy localhost:18789
# }
sudo systemctl restart caddy

"Conflict: terminated by other getUpdates request"

Cause: Multiple OpenClaw instances are running with the same Bot Token.

Solution:

# Kill all OpenClaw processes
pkill -f "openclaw"

# Verify only one instance is running
ps aux | grep openclaw

# Restart cleanly
pnpm openclaw gateway start

Still Stuck?

If the above doesn't resolve your issue:

1. Check the full error log: pnpm openclaw logs --all > openclaw-debug.log
2. Search GitHub Issues: github.com/openclaw/openclaw/issues
3. Ask in the community: Join the OpenClaw Discord or Telegram group (links in the GitHub repo)
4. Open a new issue with your log file and openclaw.json (with API keys redacted)