Troubleshooting Common OpenClaw Errors and Solutions

Clawpedia · For Humans

Quick fixes for the most common OpenClaw errors, crashes, and configuration problems.

Troubleshooting Common OpenClaw Errors and Solutions

This is a comprehensive reference for the most common OpenClaw errors and their solutions. Bookmark this page — it covers everything from installation issues to runtime errors and platform-specific problems.

Installation Errors

ErrorCauseSolution
git: command not foundGit not installedsudo apt install git (Linux) / xcode-select --install (macOS)
node: command not foundNode.js not installedInstall Node.js v18+ from nodejs.org
npm ERR! EACCESPermission issueUse sudo npm install -g openclaw or fix npm permissions
ENOSPC: no space leftDisk fullFree up disk space, need ~500 MB
node-gyp rebuild failedMissing build toolssudo apt install build-essential python3

Startup Errors

ETIMEOUT during installNetwork timeoutRetry, use VPN, or try npm mirror
ErrorCauseSolution
Port 3000 already in useAnother process on portopenclaw config set gateway.port 3001 or stop other process
Another gateway instanceOpenClaw already runningopenclaw stop then openclaw start
Config file not foundMissing configurationopenclaw init to create config
Invalid configurationSyntax error in YAMLopenclaw config validate to find the issue
ECONNREFUSED to OllamaOllama not runningStart Ollama: ollama serve

Runtime Errors

Model not foundModel not downloadedollama pull <model> or check model name
ErrorCauseSolution
Context too largeInput exceeds model limitReduce max_messages or use larger-context model
API key invalidWrong or expired API keyUpdate key: openclaw secret set <KEY>
Rate limit exceededToo many API requestsWait and retry, or switch providers
Model not allowedProvider restrictionsCheck provider dashboard for model access
Timeout waiting for responseModel too slowUse faster model or increase timeout
Memory database lockedConcurrent accessRestart OpenClaw: openclaw restart

Platform-Specific Errors

WhatsApp

Skill execution failedSkill errorCheck logs: openclaw logs --component skill:<name>
ErrorSolution
Pairing code expiredGenerate new code, have phone ready first
Session expiredRe-pair: openclaw platform whatsapp pair
Not authorizedCheck phone's WhatsApp is active and has internet

Telegram

Message failed to sendCheck WhatsApp connection status
ErrorSolution
401 UnauthorizedUpdate bot token from @BotFather
Webhook not setRun openclaw platform telegram setup

Discord

Conflict: terminated by otherOnly one instance can use a bot token
ErrorSolution
Invalid tokenRegenerate token in Discord Developer Portal
Missing permissionsRe-invite bot with correct permissions

Diagnostic Commands


# Full system diagnostic
openclaw doctor
# ✅ Node.js: v20.10.0 (required: v18+)
# ✅ Git: 2.43.0 (required: 2.30+)
# ✅ OpenClaw: v2.5.0
# ✅ Config: Valid
# ✅ Memory DB: OK (142 entries)
# ⚠️ Disk space: 2.1 GB free (recommend 5+ GB)
# ✅ Network: Connected
# ✅ Model (ollama): Responding (latency: 340ms)

# Check specific components
openclaw diagnostics network
openclaw diagnostics model
openclaw diagnostics memory
openclaw diagnostics platforms

# View error logs
openclaw logs --level error --since 24h

# View logs for specific component
openclaw logs --component gateway --tail 50
openclaw logs --component skill:email-sender --level error

Error Log Analysis


# Export logs for analysis
openclaw logs --since 7d --format json > error-report.json

# Count errors by type
openclaw logs --level error --since 24h --stats
# Error Summary (last 24h):
#   API timeout: 12 occurrences
#   Rate limit: 3 occurrences
#   Skill error: 1 occurrence
#   Total: 16 errors

Recovery Procedures

Corrupted Configuration


# Reset config to defaults
openclaw config reset
openclaw init

# Or restore from backup
openclaw backup restore --latest --only config

Corrupted Memory Database


# Try repair first
openclaw memory repair

# If repair fails, restore from backup
openclaw backup restore --latest --only memory

# Last resort: clear and start fresh
openclaw memory clear --force

Complete Reset


# Nuclear option: full reset
openclaw reset --confirm
# ⚠️ This deletes ALL data: config, memory, skills, sessions
# Start fresh:
openclaw init

Getting Help


# Built-in help
openclaw help
openclaw <command> --help

# Generate bug report (no sensitive data)
openclaw report-bug
# → Collects: version, OS, config (sanitized), recent errors
# → Opens GitHub issue template

# Community help
openclaw community --discord   # Join Discord for live help

Error Prevention

Cannot send messagesCheck bot has permission in the channel
PracticePrevents
Run openclaw doctor weeklyCatches issues early
Keep OpenClaw updatedBug fixes and stability
Use openclaw backup create before changesEasy rollback
Monitor logs with --followCatch errors in real-time
Set up alerts for disconnectionsReact to outages fast
Run as systemd serviceAuto-restart on crashes

Tip: When reporting an issue, always include the output of openclaw doctor and the relevant error logs. This helps the community diagnose your problem 10x faster.

Related Articles