Debug Guide

Run the health check first

snippbot doctor

This checks Python version, disk space, port availability, database integrity, API key presence, and server connectivity. Use --fix to attempt automatic resolution:

snippbot doctor --fix

---

Log files

All logs are written to ~/.snippbot/logs/:

File	Contents
daemon.log	Main daemon — all requests, errors, task lifecycle
executor.log	Task execution — agent prompts, tool calls, outputs
scheduler.log	Scheduler — job triggers, run outcomes
channel.log	Channel adapter — webhook events, routing

Follow logs live:

tail -f ~/.snippbot/logs/daemon.log
tail -f ~/.snippbot/logs/executor.log

Increase verbosity:

snippbot config set log_level debug
snippbot stop && snippbot start

---

Check daemon status

snippbot status

# Or directly:
curl http://localhost:18781/health

If the daemon isn’t running:

snippbot start
# If it crashes on start, check:
tail -20 ~/.snippbot/logs/daemon.log

---

Connectivity checks

1. Is the API reachable?

   curl http://localhost:18781/health
   # Expected: {"status": "ok", ...}

2. Is auth working?

   curl http://localhost:18781/api/auth/validate \
     -H "Authorization: Bearer snip_your_key"
   # Expected: {"valid": true, ...}

3. Can the AI provider be reached?

   # Test Anthropic directly
   curl https://api.anthropic.com/v1/messages \
     -H "x-api-key: $ANTHROPIC_API_KEY" \
     -H "anthropic-version: 2023-06-01" \
     -H "content-type: application/json" \
     -d '{"model":"claude-haiku-4-5-20251001","max_tokens":10,"messages":[{"role":"user","content":"hi"}]}'

4. Is the channel adapter running?

   snippbot channel status
   curl http://localhost:18790/health

---

Database inspection

All databases are standard SQLite files. Inspect them with any SQLite client:

# Install sqlite3 if needed (usually pre-installed)
sqlite3 ~/.snippbot/snippbot.db

# Useful queries:
.tables                              # list all tables
SELECT * FROM projects LIMIT 5;     # recent projects
SELECT * FROM tasks WHERE status='failed';  # failed tasks
.quit

Check database integrity:

sqlite3 ~/.snippbot/snippbot.db "PRAGMA integrity_check;"
# Expected: ok

---

Event log

All events are written to ~/.snippbot/events.jsonl:

# Watch events in real time
tail -f ~/.snippbot/events.jsonl | python3 -m json.tool

# Filter for specific event types
grep '"task.completed"' ~/.snippbot/events.jsonl | tail -10

# Count events by type
cat ~/.snippbot/events.jsonl | python3 -c "
import sys, json, collections
counts = collections.Counter()
for line in sys.stdin:
    try: counts[json.loads(line)['type']] += 1
    except: pass
for t, c in counts.most_common(20): print(f'{c:5d}  {t}')
"

---

Reset and restore

If nothing else works, reset to a clean state (a backup is always created first):

# List available backups
snippbot reset --list-backups

# Soft reset — re-run setup wizard, keep all data
snippbot reset --soft

# Full reset
snippbot reset

# Restore from backup
snippbot reset --restore pre-install-20260301-120000

---

Getting more help

• Check Common Errors for specific error messages
• Check FAQ for usage questions
• Open an issue at github.com/snippbot/snippbot/issues