> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/zeroclaw-labs/zeroclaw/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Common issues and solutions

Quick solutions to common ZeroClaw issues.

## Installation Issues

<AccordionGroup>
  <Accordion title="Homebrew installation fails">
    **Symptom**: `brew install zeroclaw` fails

    **Solutions**:

    1. Update Homebrew:

    ```bash theme={null}
    brew update
    ```

    2. Check tap status:

    ```bash theme={null}
    brew tap zeroclaw-labs/tap
    brew install zeroclaw
    ```

    3. Install from source:

    ```bash theme={null}
    git clone https://github.com/zeroclaw-labs/zeroclaw.git
    cd zeroclaw
    ./bootstrap.sh
    ```
  </Accordion>

  <Accordion title="Bootstrap script fails on low-memory systems">
    **Symptom**: `./bootstrap.sh` crashes with OOM

    **Solution**: Use pre-built binary:

    ```bash theme={null}
    ./bootstrap.sh --prefer-prebuilt
    ```

    Or increase swap:

    ```bash theme={null}
    sudo fallocate -l 4G /swapfile
    sudo chmod 600 /swapfile
    sudo mkswap /swapfile
    sudo swapon /swapfile
    ```
  </Accordion>

  <Accordion title="Cargo install fails with linking errors">
    **Symptom**: `cargo install zeroclaw` fails during linking

    **Solutions**:

    Install system dependencies:

    ```bash theme={null}
    # Debian/Ubuntu
    sudo apt install build-essential pkg-config libssl-dev

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

    # macOS
    xcode-select --install
    ```
  </Accordion>
</AccordionGroup>

## Configuration Issues

<AccordionGroup>
  <Accordion title="'Provider not configured' error">
    **Symptom**: `Error: No provider configured`

    **Solution**: Set provider credentials:

    ```bash theme={null}
    # 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
    ```
  </Accordion>

  <Accordion title="Config file not found">
    **Symptom**: `Config file not found at ~/.zeroclaw/config.toml`

    **Solution**: Initialize config:

    ```bash theme={null}
    zeroclaw config init
    ```

    Or create manually:

    ```bash theme={null}
    mkdir -p ~/.zeroclaw
    cat > ~/.zeroclaw/config.toml <<EOF
    [agent]
    provider = "anthropic"
    model = "claude-3-5-sonnet-20241022"
    EOF
    ```
  </Accordion>

  <Accordion title="Invalid TOML syntax">
    **Symptom**: `Failed to parse config: invalid TOML`

    **Solution**: Validate syntax:

    ```bash theme={null}
    # 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
  </Accordion>
</AccordionGroup>

## Channel Issues

<AccordionGroup>
  <Accordion title="Telegram bot not responding">
    **Symptom**: Bot doesn't reply to messages

    **Diagnostics**:

    ```bash theme={null}
    zeroclaw channel doctor
    ```

    **Solutions**:

    1. Check bot token:

    ```bash theme={null}
    curl https://api.telegram.org/bot<TOKEN>/getMe
    ```

    2. Verify allowlist:

    ```toml theme={null}
    [channels.telegram]
    allowed_user_ids = [123456789]  # Your Telegram user ID
    ```

    3. Check pairing mode:

    ```toml theme={null}
    [channels.telegram]
    pairing_enabled = true  # Must pair first
    ```

    4. View logs:

    ```bash theme={null}
    RUST_LOG=debug zeroclaw daemon
    ```
  </Accordion>

  <Accordion title="Discord bot offline">
    **Symptom**: Bot shows as offline in Discord

    **Solutions**:

    1. Verify token and intents:

    ```toml theme={null}
    [channels.discord]
    bot_token = "..."
    # Token must have MESSAGE_CONTENT intent enabled in Discord Developer Portal
    ```

    2. Check guild filter:

    ```toml theme={null}
    [channels.discord]
    guild_ids = ["123456789"]  # Leave empty to listen to all guilds
    ```

    3. Reconnect:

    ```bash theme={null}
    zeroclaw service restart
    ```
  </Accordion>

  <Accordion title="Email channel not receiving">
    **Symptom**: No emails trigger agent responses

    **Solutions**:

    1. Test IMAP connection:

    ```bash theme={null}
    openssl s_client -connect imap.gmail.com:993 -crlf
    # Enter: a1 LOGIN user@gmail.com password
    ```

    2. Enable IMAP IDLE:

    ```toml theme={null}
    [channels.email]
    imap_idle = true  # Required for push notifications
    ```

    3. Check allowlist:

    ```toml theme={null}
    [channels.email]
    allowed_senders = ["user@example.com", "@company.com"]
    ```
  </Accordion>
</AccordionGroup>

## Provider Issues

<AccordionGroup>
  <Accordion title="'Rate limit exceeded' errors">
    **Symptom**: `429 Too Many Requests`

    **Solutions**:

    1. Implement rate limiting:

    ```toml theme={null}
    [security]
    max_actions_per_hour = 50
    rate_limit_per_minute = 10
    ```

    2. Add retry backoff:

    ```toml theme={null}
    [providers.anthropic]
    max_retries = 3
    retry_backoff_ms = 1000
    ```

    3. Switch to different provider temporarily
  </Accordion>

  <Accordion title="Provider connection timeout">
    **Symptom**: `Connection timeout after 30s`

    **Solutions**:

    1. Check network connectivity:

    ```bash theme={null}
    curl -v https://api.anthropic.com/v1/messages
    ```

    2. Increase timeout:

    ```toml theme={null}
    [providers.anthropic]
    timeout_seconds = 60
    ```

    3. Configure proxy if needed:

    ```bash theme={null}
    export HTTPS_PROXY=http://proxy.example.com:8080
    ```
  </Accordion>

  <Accordion title="'Invalid API key' error">
    **Symptom**: `401 Unauthorized: Invalid API key`

    **Solutions**:

    1. Verify key format:

    ```bash theme={null}
    # Anthropic: sk-ant-api03-...
    # OpenAI: sk-...
    echo $ANTHROPIC_API_KEY
    ```

    2. Regenerate key in provider dashboard

    3. Check key hasn't been rotated:

    ```bash theme={null}
    zeroclaw config get providers.anthropic.api_key
    ```
  </Accordion>
</AccordionGroup>

## Runtime Issues

<AccordionGroup>
  <Accordion title="Service won't start">
    **Symptom**: `zeroclaw service start` fails

    **Diagnostics**:

    ```bash theme={null}
    # Check service status
    zeroclaw service status

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

    **Solutions**:

    1. Verify config:

    ```bash theme={null}
    zeroclaw doctor
    ```

    2. Check file permissions:

    ```bash theme={null}
    ls -la ~/.zeroclaw/
    chmod 755 ~/.zeroclaw
    ```

    3. Reinstall service:

    ```bash theme={null}
    zeroclaw service uninstall
    zeroclaw service install
    zeroclaw service start
    ```
  </Accordion>

  <Accordion title="High memory usage">
    **Symptom**: Process using >100MB RAM

    **Solutions**:

    1. Check memory stats:

    ```bash theme={null}
    zeroclaw status
    ```

    2. Limit conversation history:

    ```toml theme={null}
    [memory]
    max_entries = 1000
    max_conversation_turns = 50
    ```

    3. Reduce tool output buffering:

    ```toml theme={null}
    [tools]
    max_output_bytes = 524288  # 512KB instead of 1MB
    ```
  </Accordion>

  <Accordion title="Gateway bind error">
    **Symptom**: `Address already in use (port 3000)`

    **Solutions**:

    1. Find conflicting process:

    ```bash theme={null}
    lsof -i :3000
    # Kill if needed
    kill -9 <PID>
    ```

    2. Use different port:

    ```bash theme={null}
    zeroclaw gateway --port 3001
    ```

    Or in config:

    ```toml theme={null}
    [gateway]
    port = 3001
    ```
  </Accordion>
</AccordionGroup>

## Tool Execution Issues

<AccordionGroup>
  <Accordion title="Shell commands blocked">
    **Symptom**: `Command blocked by security policy`

    **Solution**: Review blocked commands:

    ```bash theme={null}
    zeroclaw config get security.blocked_commands
    ```

    Adjust if needed:

    ```toml theme={null}
    [security]
    blocked_commands = ["rm -rf /", "dd if="]
    # Remove overly broad patterns
    ```
  </Accordion>

  <Accordion title="File access denied">
    **Symptom**: `Path outside workspace`

    **Solution**: Verify workspace path:

    ```bash theme={null}
    zeroclaw config get security.workspace_path
    ```

    Set explicitly:

    ```toml theme={null}
    [security]
    workspace_path = "/home/user/projects"
    ```
  </Accordion>

  <Accordion title="Browser tool not working">
    **Symptom**: `WebDriver connection failed`

    **Solution**: Start WebDriver:

    ```bash theme={null}
    # ChromeDriver
    chromedriver --port=9515 &

    # Or use HTTP backend (no WebDriver needed)
    zeroclaw config set tools.browser_backend http
    ```
  </Accordion>
</AccordionGroup>

## Hardware Issues

<AccordionGroup>
  <Accordion title="Peripheral not detected">
    **Symptom**: `Failed to connect to peripheral`

    **Solutions**:

    1. Check USB connection:

    ```bash theme={null}
    lsusb  # Linux
    system_profiler SPUSBDataType  # macOS
    ```

    2. Verify serial port:

    ```bash theme={null}
    ls /dev/tty*  # Look for /dev/ttyUSB0 or /dev/ttyACM0
    ```

    3. Add user to dialout group (Linux):

    ```bash theme={null}
    sudo usermod -a -G dialout $USER
    # Log out and back in
    ```
  </Accordion>

  <Accordion title="Raspberry Pi GPIO not working">
    **Symptom**: `GPIO access denied`

    **Solution**: Enable GPIO permissions:

    ```bash theme={null}
    # Add user to gpio group
    sudo usermod -a -G gpio $USER

    # Or run with sudo (not recommended)
    sudo zeroclaw daemon
    ```

    Build with GPIO support:

    ```bash theme={null}
    cargo build --features peripheral-rpi
    ```
  </Accordion>
</AccordionGroup>

## Getting Help

If you're still stuck:

1. **Check logs** with increased verbosity:
   ```bash theme={null}
   RUST_LOG=debug zeroclaw daemon
   ```

2. **Run diagnostics**:
   ```bash theme={null}
   zeroclaw doctor
   zeroclaw channel doctor
   zeroclaw status
   ```

3. **Search issues**: [GitHub Issues](https://github.com/zeroclaw-labs/zeroclaw/issues)

4. **Ask for help**:
   * [Telegram Community](https://t.me/zeroclawlabs)
   * [GitHub Discussions](https://github.com/zeroclaw-labs/zeroclaw/discussions)

## Related

* [Running Agents](/operations/running-agents)
* [Monitoring](/operations/monitoring)
* [Security Best Practices](/operations/security-best-practices)