Troubleshooting

Common issues and solutions

Quick solutions to common ZeroClaw issues.

Installation Issues

Homebrew installation fails

Symptom: brew install zeroclaw fails

Solutions:

1. Update Homebrew:

brew update

2. Check tap status:

brew tap zeroclaw-labs/tap
brew install zeroclaw

3. Install from source:

git clone https://github.com/zeroclaw-labs/zeroclaw.git
cd zeroclaw
./bootstrap.sh

Bootstrap script fails on low-memory systems

Symptom: ./bootstrap.sh crashes with OOM

Solution: 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

Cargo install fails with linking errors

Symptom: cargo install zeroclaw fails during linking

Solutions:

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

'Provider not configured' error

Symptom: Error: No provider configured

Solution: 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

Config file not found

Symptom: Config file not found at ~/.zeroclaw/config.toml

Solution: 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

Invalid TOML syntax

Symptom: Failed to parse config: invalid TOML

Solution: 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

Telegram bot not responding

Symptom: Bot doesn’t reply to messages

Diagnostics:

zeroclaw channel doctor

Solutions:

1. Check bot token:

curl https://api.telegram.org/bot<TOKEN>/getMe

2. Verify allowlist:

[channels.telegram]
allowed_user_ids = [123456789]  # Your Telegram user ID

3. Check pairing mode:

[channels.telegram]
pairing_enabled = true  # Must pair first

4. View logs:

RUST_LOG=debug zeroclaw daemon

Discord bot offline

Symptom: Bot shows as offline in Discord

Solutions:

1. Verify token and intents:

[channels.discord]
bot_token = "..."
# Token must have MESSAGE_CONTENT intent enabled in Discord Developer Portal

2. Check guild filter:

[channels.discord]
guild_ids = ["123456789"]  # Leave empty to listen to all guilds

3. Reconnect:

zeroclaw service restart

Email channel not receiving

Symptom: No emails trigger agent responses

Solutions:

1. Test IMAP connection:

openssl s_client -connect imap.gmail.com:993 -crlf
# Enter: a1 LOGIN [e-mail] password

2. Enable IMAP IDLE:

[channels.email]
imap_idle = true  # Required for push notifications

3. Check allowlist:

[channels.email]
allowed_senders = ["[e-mail]", "@company.com"]

Provider Issues

'Rate limit exceeded' errors

Symptom: 429 Too Many Requests

Solutions:

1. Implement rate limiting:

[security]
max_actions_per_hour = 50
rate_limit_per_minute = 10

2. Add retry backoff:

[providers.anthropic]
max_retries = 3
retry_backoff_ms = 1000

3. Switch to different provider temporarily

Provider connection timeout

Symptom: Connection timeout after 30s

Solutions:

1. Check network connectivity:

curl -v https://api.anthropic.com/v1/messages

2. Increase timeout:

[providers.anthropic]
timeout_seconds = 60

3. Configure proxy if needed:

export HTTPS_PROXY=http://proxy.example.com:8080

'Invalid API key' error

Symptom: 401 Unauthorized: Invalid API key

Solutions:

1. Verify key format:

# Anthropic: sk-ant-api03-...
# OpenAI: sk-...
echo $ANTHROPIC_API_KEY

2. Regenerate key in provider dashboard

3. Check key hasn’t been rotated:

zeroclaw config get providers.anthropic.api_key

Runtime Issues

Service won't start

Symptom: zeroclaw service start fails

Diagnostics:

# Check service status
zeroclaw service status

# View logs
journalctl --user -u zeroclaw.service -n 50

Solutions:

1. Verify config:

zeroclaw doctor

2. Check file permissions:

ls -la ~/.zeroclaw/
chmod 755 ~/.zeroclaw

3. Reinstall service:

zeroclaw service uninstall
zeroclaw service install
zeroclaw service start

High memory usage

Symptom: Process using >100MB RAM

Solutions:

1. Check memory stats:

zeroclaw status

2. Limit conversation history:

[memory]
max_entries = 1000
max_conversation_turns = 50

3. Reduce tool output buffering:

[tools]
max_output_bytes = 524288  # 512KB instead of 1MB

Gateway bind error

Symptom: Address already in use (port 3000)

Solutions:

1. Find conflicting process:

lsof -i :3000
# Kill if needed
kill -9 <PID>

2. Use different port:

zeroclaw gateway --port 3001

Or in config:

[gateway]
port = 3001

Tool Execution Issues

Shell commands blocked

Symptom: Command blocked by security policy

Solution: Review blocked commands:

zeroclaw config get security.blocked_commands

Adjust if needed:

[security]
blocked_commands = ["rm -rf /", "dd if="]
# Remove overly broad patterns

File access denied

Symptom: Path outside workspace

Solution: Verify workspace path:

zeroclaw config get security.workspace_path

Set explicitly:

[security]
workspace_path = "/home/user/projects"

Browser tool not working

Symptom: WebDriver connection failed

Solution: Start WebDriver:

# ChromeDriver
chromedriver --port=9515 &

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

Hardware Issues

Peripheral not detected

Symptom: Failed to connect to peripheral

Solutions:

1. Check USB connection:

lsusb  # Linux
system_profiler SPUSBDataType  # macOS

2. Verify serial port:

ls /dev/tty*  # Look for /dev/ttyUSB0 or /dev/ttyACM0

3. Add user to dialout group (Linux):

sudo usermod -a -G dialout $USER
# Log out and back in

Raspberry Pi GPIO not working

Symptom: GPIO access denied

Solution: 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:

   • Telegram Community
   • GitHub Discussions

Related

• Running Agents
• Monitoring
• Security Best Practices