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 routing.allowFrom?

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

Check 2: For group chats, is mention required?

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

Check 3: Check the logs

tail -f "$(ls -t /tmp/clawdis/clawdis-*.log | head -1)" | 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, /reset, 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 local status (creds, sessions, queued events)
clawdis status
# Probe the running gateway + providers (WA connect + Telegram + Discord APIs)
clawdis status --deep

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

Fix: Usually reconnects automatically once the Gateway is running. If you’re stuck, restart the Gateway process (however you supervise it), or run it manually with verbose output:

clawdis gateway --verbose

If you’re logged out / unlinked:

clawdis logout
rm -rf ~/.clawdis/credentials # if logout can't cleanly remove everything
clawdis login --verbose       # re-scan QR

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" "$(ls -t /tmp/clawdis/clawdis-*.log | head -1)" | 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
  }
}

macOS Specific Issues

App Crashes when Granting Permissions (Speech/Mic)

If the app disappears or shows "Abort trap 6" when you click "Allow" on a privacy prompt:

Fix 1: Reset TCC Cache

tccutil reset All com.steipete.clawdis.debug

Fix 2: Force New Bundle ID If resetting doesn't work, change the BUNDLE_ID in scripts/package-mac-app.sh (e.g., add a .test suffix) and rebuild. This forces macOS to treat it as a new app.

Gateway stuck on "Starting..."

The app connects to a local gateway on port 18789. If it stays stuck:

Fix 1: Kill Zombie Processes Another process might be holding the port.

lsof -nP -i :18789
# Kill any matching PIDs
kill -9 <PID>

Fix 2: Check embedded gateway Ensure the gateway relay was properly bundled. Run ./scripts/package-mac-app.sh and ensure bun is installed.

Debug Mode

Get verbose logging:

# Turn on trace logging in config:
#   ~/.clawdis/clawdis.json -> { logging: { level: "trace" } }
#
# Then run verbose commands to mirror debug output to stdout:
clawdis gateway --verbose
clawdis login --verbose

Log Locations

Log	Location
Main logs (default)	/tmp/clawdis/clawdis-YYYY-MM-DD.log
Session files	~/.clawdis/sessions/
Media cache	~/.clawdis/media/
Credentials	~/.clawdis/credentials/

Health Check

# Is the gateway reachable?
clawdis health --json

# Is something listening on the default port?
lsof -nP -iTCP:18789 -sTCP:LISTEN

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

Reset Everything

Nuclear option:

rm -rf ~/.clawdis
clawdis login         # re-pair WhatsApp
clawdis gateway        # start the Gateway again

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

Getting Help

1. Check logs first: /tmp/clawdis/ (default: clawdis-YYYY-MM-DD.log, or your configured logging.file)
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

🦞🔧