Debug and fix common Clawdbot AI assistant issues. Learn how to diagnose connection problems, message failures, and gateway errors.

Clawdbot Troubleshooting Overview

This guide helps you diagnose and fix common issues with your Clawdbot deployment. Find solutions for connection problems, message failures, and gateway errors.

Common Issues

Gateway Won't Start

Symptoms: Gateway fails to start or exits immediately.

Solutions:

Check port availability:

lsof -i :3010

Verify configuration:

clawdbot config validate

Check logs:

clawdbot gateway logs

WhatsApp Connection Failed

Symptoms: QR code not showing or connection drops.

Solutions:

Clear WhatsApp session:

rm -rf ~/.clawdbot/providers/whatsapp/session

Restart gateway:

clawdbot gateway restart

Check network connectivity

Messages Not Delivered

Symptoms: Messages sent but not received.

Solutions:

Check session status:

clawdbot sessions list

Verify provider connection:

clawdbot providers status

Check rate limits

Agent Not Responding

Symptoms: Agent doesn't generate responses.

Solutions:

Check agent status:

clawdbot agents status

Verify API key:

echo $ANTHROPIC_API_KEY

Check model availability

Diagnostic Commands

Gateway Status

# Check gateway health
clawdbot gateway status

# View active connections
clawdbot gateway connections

# Show resource usage
clawdbot gateway stats

Session Diagnostics

# List all sessions
clawdbot sessions list

# View session details
clawdbot sessions get <session-key>

# Clear stuck session
clawdbot sessions clear <session-key>

Provider Diagnostics

# Check provider status
clawdbot providers status

# Test provider connection
clawdbot providers test whatsapp

# Reconnect provider
clawdbot providers reconnect telegram

Log Analysis

Enable Debug Logging

clawdbot gateway start --log-level debug

Log Locations

Log	Location
Gateway	`~/.clawdbot/logs/gateway.log`
Providers	`~/.clawdbot/logs/providers/`
Agents	`~/.clawdbot/logs/agents/`

Log Levels

Level	Description
`error`	Errors only
`warn`	Warnings and errors
`info`	General information
`debug`	Detailed debug info

Error Codes

Connection Errors

Code	Description	Solution
`ECONNREFUSED`	Port not open	Check gateway is running
`ETIMEDOUT`	Network timeout	Check network
`EAUTH`	Auth failed	Verify credentials

Provider Errors

Code	Description	Solution
`WA_DISCONNECTED`	WhatsApp disconnected	Rescan QR
`TG_INVALID_TOKEN`	Bad Telegram token	Check token
`DC_MISSING_INTENTS`	Discord intents	Enable intents

Performance Issues

Slow Responses

Causes:

High message volume
Large context size
Network latency

Solutions:

Enable streaming
Reduce context size
Check network

Memory Usage

Check memory:

clawdbot gateway stats --memory

Reduce memory:

{
  "gateway": {
    "messageBuffer": 500,
    "maxHistory": 50
  }
}

Recovery Procedures

Reset Gateway

# Stop gateway
clawdbot gateway stop

# Clear state
clawdbot gateway reset --state

# Restart
clawdbot gateway start

Reset Provider

# Disconnect provider
clawdbot providers disconnect whatsapp

# Clear provider data
rm -rf ~/.clawdbot/providers/whatsapp

# Reconfigure
clawdbot providers setup whatsapp

Reset Agent

# Clear agent sessions
clawdbot agents reset main --sessions

# Clear agent workspace
clawdbot agents reset main --workspace

Getting Help

Support Resources

Documentation: https://docs.clawdbotai.app
GitHub Issues: https://github.com/clawdbot/clawdbot/issues
Community Discord: https://discord.gg/clawdbot

Bug Reports

Include in bug reports:

Clawdbot version
Operating system
Error messages
Steps to reproduce

Next Steps

Clawdbot Configuration - Configuration guide
Clawdbot Security - Security setup
Clawdbot Gateway - Gateway overview

Clawdbot Troubleshooting

On this page