Troubleshooting

Fix common issues and resolve problems

Common Issues

Gateway Won't Start

Possible causes:

  • Node.js version is too old (requires ≥22)
  • Port 18789 is already in use
  • Configuration file has syntax errors
  • Missing dependencies

Solutions:

  1. Run clawdbot doctor to check for configuration issues
  2. Verify Node.js version: node --version
  3. Check if port is in use: lsof -i :18789 (macOS/Linux)
  4. Review configuration file: ~/.clawdbot/clawdbot.json
  5. Reinstall: npm install -g clawdbot@latest

Channel Not Connecting

Possible causes:

  • Incorrect credentials or tokens
  • Missing environment variables
  • Network connectivity issues
  • Channel-specific configuration errors

Solutions:

  1. Verify credentials are correct
  2. For WhatsApp, ensure you've completed the pairing process
  3. Check ~/.clawdbot/credentials for stored credentials
  4. Verify environment variables are set correctly
  5. Check channel-specific documentation in Channels Guide
  6. Enable verbose logging: clawdbot gateway --verbose

Permission Errors (macOS)

Possible causes:

  • Missing macOS permissions in System Settings
  • Screen recording permission not granted
  • Accessibility permissions missing

Solutions:

  1. Open System Settings → Privacy & Security
  2. Grant necessary permissions:
    • Screen Recording
    • Accessibility
    • Full Disk Access (if needed)
  3. For screen recording, set needsScreenRecording: true in tool calls
  4. Restart the Gateway after granting permissions

Model Authentication Issues

Possible causes:

  • Invalid API keys
  • Expired OAuth tokens
  • Incorrect model configuration
  • Rate limiting or quota exceeded

Solutions:

  1. Verify API keys or OAuth tokens are valid
  2. Check model configuration in ~/.clawdbot/clawdbot.json
  3. Test authentication: clawdbot agent --message "test"
  4. Check provider dashboard for rate limits or quotas
  5. Configure model failover for reliability

Skills Not Working

Possible causes:

  • Skill file syntax errors
  • Missing dependencies
  • Incorrect skill configuration
  • Permission issues

Solutions:

  1. Check skill files in ~/clawd/skills/
  2. Review skill logs for errors
  3. Verify skill dependencies are installed
  4. Test skill manually
  5. Recreate skill if needed

Browser Control Not Working

Possible causes:

  • Chrome/Chromium not installed
  • Browser control not enabled
  • Linux-specific display issues

Solutions:

  1. Verify Chrome/Chromium is installed
  2. Enable browser control in config: browser.enabled: true
  3. On Linux, ensure display is available (X11 or Wayland)
  4. Check browser control URL configuration

Health Checks

Run clawdbot doctor to perform comprehensive health checks:

  • Check for configuration issues
  • Surface risky/misconfigured DM policies
  • Verify gateway status
  • Check for updates
  • Validate channel configurations
  • Check workspace integrity
Health Check Command 
clawdbot doctor

Logging

Enable verbose logging to diagnose issues:

Verbose Logging 
clawdbot gateway --verbose

Or set verboseLevel in your configuration file for persistent verbose output.

Log locations:

  • Gateway logs: Check terminal output or system logs
  • Channel logs: Per-channel logging in workspace
  • Agent logs: Session logs in workspace

Gateway Lock

If the Gateway appears locked or won't start:

  1. Check for lock file: ~/.clawdbot/gateway.lock
  2. Verify no other Gateway instance is running
  3. Remove lock file if Gateway process is not running: rm ~/.clawdbot/gateway.lock
  4. Restart Gateway

Background Process

If Gateway is running as a background service:

  • macOS: Check launchd: launchctl list | grep clawdbot
  • Linux: Check systemd: systemctl --user status clawdbot
  • View logs: journalctl -u clawdbot (Linux) or check Console.app (macOS)
  • Restart service: systemctl --user restart clawdbot (Linux)

Browser Troubleshooting (Linux)

On Linux, browser control may require additional setup:

  • Install Chrome/Chromium: sudo apt install chromium-browser (Debian/Ubuntu)
  • Ensure display server is running (X11 or Wayland)
  • Set DISPLAY environment variable if needed
  • Use headless mode if no display available

Getting Help

If you're still experiencing issues:

  1. Run clawdbot doctor and review all output
  2. Enable verbose logging and capture error messages
  3. Check the Configuration Guide for settings
  4. Review Channels Guide for channel-specific issues
  5. Check workspace files for errors

Related Documentation