Skip to main content
Quick solutions to common ZeroClaw issues.

​
Installation Issues

Symptom: brew install zeroclaw failsSolutions:
  1. Update Homebrew:
brew update
  1. Check tap status:
brew tap zeroclaw-labs/tap
brew install zeroclaw
  1. Install from source:
git clone https://github.com/zeroclaw-labs/zeroclaw.git
cd zeroclaw
./bootstrap.sh
Symptom: ./bootstrap.sh crashes with OOMSolution: Use pre-built binary:
./bootstrap.sh --prefer-prebuilt
Or increase swap:
sudo fallocate -l 4G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
Symptom: cargo install zeroclaw fails during linkingSolutions:Install system dependencies:
# Debian/Ubuntu
sudo apt install build-essential pkg-config libssl-dev

# Fedora
sudo dnf install gcc pkg-config openssl-devel

# macOS
xcode-select --install

​
Configuration Issues

Symptom: Error: No provider configuredSolution: Set provider credentials:
# Option 1: Environment variable
export ANTHROPIC_API_KEY="sk-ant-..."

# Option 2: Config file
zeroclaw config set agent.provider anthropic
zeroclaw config set providers.anthropic.api_key "sk-ant-..."

# Verify
zeroclaw status
Symptom: Config file not found at ~/.zeroclaw/config.tomlSolution: Initialize config:
zeroclaw config init
Or create manually:
mkdir -p ~/.zeroclaw
cat > ~/.zeroclaw/config.toml <<EOF
[agent]
provider = "anthropic"
model = "claude-3-5-sonnet-20241022"
EOF
Symptom: Failed to parse config: invalid TOMLSolution: Validate syntax:
# Check for common issues
cat ~/.zeroclaw/config.toml

# Regenerate config
mv ~/.zeroclaw/config.toml ~/.zeroclaw/config.toml.bak
zeroclaw config init
Common mistakes:
  • Missing quotes around strings
  • Unclosed brackets
  • Invalid escape sequences

​
Channel Issues

Symptom: Bot doesn’t reply to messagesDiagnostics:
zeroclaw channel doctor
Solutions:
  1. Check bot token:
curl https://api.telegram.org/bot<TOKEN>/getMe
  1. Verify allowlist:
[channels.telegram]
allowed_user_ids = [123456789]  # Your Telegram user ID
  1. Check pairing mode:
[channels.telegram]
pairing_enabled = true  # Must pair first
  1. View logs:
RUST_LOG=debug zeroclaw daemon
Symptom: Bot shows as offline in DiscordSolutions:
  1. Verify token and intents:
[channels.discord]
bot_token = "..."
# Token must have MESSAGE_CONTENT intent enabled in Discord Developer Portal
  1. Check guild filter:
[channels.discord]
guild_ids = ["123456789"]  # Leave empty to listen to all guilds
  1. Reconnect:
zeroclaw service restart
Symptom: No emails trigger agent responsesSolutions:
  1. Test IMAP connection:
openssl s_client -connect imap.gmail.com:993 -crlf
# Enter: a1 LOGIN [email protected] password
  1. Enable IMAP IDLE:
[channels.email]
imap_idle = true  # Required for push notifications
  1. Check allowlist:
[channels.email]
allowed_senders = ["[email protected]", "@company.com"]

​
Provider Issues

Symptom: 429 Too Many RequestsSolutions:
  1. Implement rate limiting:
[security]
max_actions_per_hour = 50
rate_limit_per_minute = 10
  1. Add retry backoff:
[providers.anthropic]
max_retries = 3
retry_backoff_ms = 1000
  1. Switch to different provider temporarily
Symptom: Connection timeout after 30sSolutions:
  1. Check network connectivity:
curl -v https://api.anthropic.com/v1/messages
  1. Increase timeout:
[providers.anthropic]
timeout_seconds = 60
  1. Configure proxy if needed:
export HTTPS_PROXY=http://proxy.example.com:8080
Symptom: 401 Unauthorized: Invalid API keySolutions:
  1. Verify key format:
# Anthropic: sk-ant-api03-...
# OpenAI: sk-...
echo $ANTHROPIC_API_KEY
  1. Regenerate key in provider dashboard
  2. Check key hasn’t been rotated: 
zeroclaw config get providers.anthropic.api_key

​
Runtime Issues

Symptom: zeroclaw service start failsDiagnostics:
# Check service status
zeroclaw service status

# View logs
journalctl --user -u zeroclaw.service -n 50
Solutions:
  1. Verify config:
zeroclaw doctor
  1. Check file permissions:
ls -la ~/.zeroclaw/
chmod 755 ~/.zeroclaw
  1. Reinstall service:
zeroclaw service uninstall
zeroclaw service install
zeroclaw service start
Symptom: Process using >100MB RAMSolutions:
  1. Check memory stats:
zeroclaw status
  1. Limit conversation history:
[memory]
max_entries = 1000
max_conversation_turns = 50
  1. Reduce tool output buffering:
[tools]
max_output_bytes = 524288  # 512KB instead of 1MB
Symptom: Address already in use (port 3000)Solutions:
  1. Find conflicting process:
lsof -i :3000
# Kill if needed
kill -9 <PID>
  1. Use different port:
zeroclaw gateway --port 3001
Or in config:
[gateway]
port = 3001

​
Tool Execution Issues

Symptom: Command blocked by security policySolution: Review blocked commands:
zeroclaw config get security.blocked_commands
Adjust if needed:
[security]
blocked_commands = ["rm -rf /", "dd if="]
# Remove overly broad patterns
Symptom: Path outside workspaceSolution: Verify workspace path:
zeroclaw config get security.workspace_path
Set explicitly:
[security]
workspace_path = "/home/user/projects"
Symptom: WebDriver connection failedSolution: Start WebDriver:
# ChromeDriver
chromedriver --port=9515 &

# Or use HTTP backend (no WebDriver needed)
zeroclaw config set tools.browser_backend http

​
Hardware Issues

Symptom: Failed to connect to peripheralSolutions:
  1. Check USB connection:
lsusb  # Linux
system_profiler SPUSBDataType  # macOS
  1. Verify serial port:
ls /dev/tty*  # Look for /dev/ttyUSB0 or /dev/ttyACM0
  1. Add user to dialout group (Linux):
sudo usermod -a -G dialout $USER
# Log out and back in
Symptom: GPIO access deniedSolution: Enable GPIO permissions:
# Add user to gpio group
sudo usermod -a -G gpio $USER

# Or run with sudo (not recommended)
sudo zeroclaw daemon
Build with GPIO support:
cargo build --features peripheral-rpi

​
Getting Help

If you’re still stuck:
  1. Check logs with increased verbosity: 
    RUST_LOG=debug zeroclaw daemon
  2. Run diagnostics: 
    zeroclaw doctor
zeroclaw channel doctor
zeroclaw status
  3. Search issues: GitHub Issues
  4. Ask for help:

Build docs developers (and LLMs) love

Get started for freeTalk to us