clawdbot/docs/troubleshooting.md

summary, read_when

summary	read_when
Quick troubleshooting guide for common Clawdis failures	Investigating runtime issues or failures

Troubleshooting 🔧

When your CLAWDIS misbehaves, here's how to fix it.

Common Issues

"Agent was aborted"

The agent was interrupted mid-response.

Causes:

• User sent stop, abort, esc, or exit
• Timeout exceeded
• Process crashed

Fix: Just send another message. The session continues.

Messages Not Triggering

Check 1: Is the sender in allowFrom?

cat ~/.clawdis/clawdis.json | jq '.inbound.allowFrom'

Check 2: For group chats, is mention required?

# The message must contain a pattern from mentionPatterns
cat ~/.clawdis/clawdis.json | jq '.inbound.groupChat'

Check 3: Check the logs

tail -f /tmp/clawdis/clawdis.log | grep "blocked\|skip\|unauthorized"

Image + Mention Not Working

Known issue: When you send an image with ONLY a mention (no other text), WhatsApp sometimes doesn't include the mention metadata.

Workaround: Add some text with the mention:

• ❌ @clawd + image
• ✅ @clawd check this + image

Session Not Resuming

Check 1: Is the session file there?

ls -la ~/.clawdis/sessions/

Check 2: Is idleMinutes too short?

{
  "session": {
    "idleMinutes": 10080  // 7 days
  }
}

Check 3: Did someone send /new or a reset trigger?

Agent Timing Out

Default timeout is 30 minutes. For long tasks:

{
  "reply": {
    "timeoutSeconds": 3600  // 1 hour
  }
}

Or use the process tool to background long commands.

WhatsApp Disconnected

# Check status
clawdis status
# Or from chat: send /status for agent + context usage

# View recent connection events
tail -100 /tmp/clawdis/clawdis.log | grep "connection\|disconnect\|logout"

Fix: Usually reconnects automatically. If not:

clawdis restart

If you're logged out:

clawdis stop
rm -rf ~/.clawdis/credentials  # Clear session
clawdis start  # Re-scan QR code

Media Send Failing

Check 1: Is the file path valid?

ls -la /path/to/your/image.jpg

Check 2: Is it too large?

• Images: max 6MB
• Audio/Video: max 16MB
• Documents: max 100MB

Check 3: Check media logs

grep "media\|fetch\|download" /tmp/clawdis/clawdis.log | tail -20

High Memory Usage

CLAWDIS keeps conversation history in memory.

Fix: Restart periodically or set session limits:

{
  "session": {
    "historyLimit": 100  // Max messages to keep
  }
}

Debug Mode

Get verbose logging:

# In config
{
  "logging": {
    "level": "trace"
  }
}

# Or environment
CLAWDIS_LOG_LEVEL=trace clawdis start

Log Locations

Log	Location
Main log	/tmp/clawdis/clawdis.log
Session files	~/.clawdis/sessions/
Media cache	~/.clawdis/media/
Credentials	~/.clawdis/credentials/

Health Check

# Is it running?
clawdis status

# Check the socket
ls -la ~/.clawdis/clawdis.sock

# Recent activity
tail -20 /tmp/clawdis/clawdis.log

Reset Everything

Nuclear option:

clawdis stop
rm -rf ~/.clawdis
clawdis start  # Fresh setup

⚠️ This loses all sessions and requires re-pairing WhatsApp.

Getting Help

1. Check logs first: /tmp/clawdis/clawdis.log
2. Search existing issues on GitHub
3. Open a new issue with:
   • CLAWDIS version
   • Relevant log snippets
   • Steps to reproduce
   • Your config (redact secrets!)

---

"Have you tried turning it off and on again?" — Every IT person ever

🦞🔧