10 Common Clawdbot Errors and How to Fix Them

Quick fixes for the most frustrating Clawdbot issues.

8 min read • By ByteDoc

Clawdbot is powerful, but sometimes things break. Here are the 10 most common errors and exactly how to fix them.

1. "clawdbot: command not found"

What it means: Your system can't find the clawdbot command because it's not in your PATH.

Fix it:

First, find where Clawdbot is installed:

Then add the npm bin directory to your PATH. For most systems:

Make it permanent by adding that line to your ~/.bashrc or ~/.zshrc:

Then reload:

2. "No API key found for provider 'anthropic'"

What it means: You haven't set up your API key, or it's not being read correctly.

Fix it:

Run the setup wizard again:

Or manually add your key. Create/edit ~/.clawdbot/.env:

Then restart the Gateway:

3. Gateway Won't Start / "Address Already in Use"

What it means: Something else is using port 18789, or a previous Gateway instance didn't shut down cleanly.

Fix it:

Find what's using the port:

Kill the process:

Or kill all Clawdbot processes:

Then start fresh:

4. WhatsApp Keeps Disconnecting

What it means: The WhatsApp session expired or got invalidated.

Common causes:

• You logged into WhatsApp Web elsewhere
• Your phone's internet is unstable
• WhatsApp pushed an update
• Session timeout (happens occasionally)

Fix it:

Re-link WhatsApp:

Scan the new QR code with your phone.

Prevention: Don't use WhatsApp Web on other devices while Clawdbot is connected. If you have Bun installed, switch to Node — Bun has known WhatsApp issues.

5. "Unauthorized" / Gateway Authentication Failed

What it means: The CLI and Gateway aren't using the same authentication token.

Fix it:

Check your Gateway token:

Make sure your CLI is using the same token. If they don't match, re-run onboarding:

Or reset credentials:

6. Messages Not Being Delivered

What it means: The Gateway is running but messages aren't going through.

Check these:

1. Is the Gateway actually running?

2. Check the logs for errors:

3. Is the channel connected?

4. Did you approve the pairing? First DMs require approval:

7. "Model not allowed" Error

What it means: Your configuration restricts which models can be used, and you're trying to use one that's not on the list.

Fix it:

Check your model allowlist:

Either use an allowed model, or edit your config to allow the model you want:

Look for models.allowlist and add your model, or remove the allowlist to allow all.

8. Rate Limited / 429 Errors

What it means: You've hit API rate limits — too many requests too fast.

Fix it:

• Wait: Rate limits usually reset within a minute
• Check usage: Log into your Anthropic/OpenAI dashboard
• Add billing: Free tiers have strict limits — add a payment method
• Use multiple providers: Set up failover to another model

To set up failover, add multiple providers in your config so it automatically switches when one fails.

9. Linux: Gateway Stops When I Log Out

What it means: Systemd is killing your user services when you disconnect SSH.

Fix it:

Enable lingering for your user:

Then reinstall the Gateway service:

Now the Gateway stays running even after you log out.

10. SSL/Connection Errors (Especially Comcast/Xfinity)

What it means: Your ISP or network security is blocking Clawdbot's connections.

Common with: Xfinity Advanced Security, corporate networks, some VPNs.

Fix it:

• Xfinity users: Disable "Advanced Security" in your Xfinity app or router settings
• Corporate networks: Try running on a personal hotspot to test
• VPN users: Try disconnecting your VPN

Diagnostic Commands

When something's wrong, run these to gather info:

• clawdbot status — Overall health check
• clawdbot doctor — Diagnose common issues
• clawdbot logs — Recent log output
• clawdbot logs --level error — Only errors
• clawdbot status --all — Full system info (useful for bug reports)

Nuclear Option: Fresh Start

If nothing works, you can reset everything:

Warning: This wipes your configuration. You'll need to set up everything again.

Then re-run the wizard:

Getting More Help

• Docs: docs.clawd.bot
• Discord: discord.com/invite/clawd
• GitHub Issues: github.com/clawdbot/clawdbot

When asking for help, always include the output of clawdbot status --all and relevant logs. Makes troubleshooting way faster.

Good luck! 🦞