Troubleshooting

# 1. Is the service running?
launchctl list | grep nanoclaw
# Expected: PID  0  com.nanoclaw (PID = running, "-" = not running, non-zero exit = crashed)

# 2. Any running containers?
docker ps --format '{{.Names}} {{.Status}}' 2>/dev/null | grep nanoclaw

# 3. Any stopped/orphaned containers?
docker ps -a --format '{{.Names}} {{.Status}}' 2>/dev/null | grep nanoclaw

# 4. Recent errors in service log?
grep -E 'ERROR|WARN' logs/nanoclaw.log | tail -20

# 5. Are channels connected? (look for last connection event)
grep -E 'Connected|Connection closed|connection.*close' logs/nanoclaw.log | tail -5

# 6. Are groups loaded?
grep 'groupCount' logs/nanoclaw.log | tail -3

# Check for recent timeouts
grep -E 'Container timeout|timed out' logs/nanoclaw.log | tail -10

# Check container log files
ls -lt groups/*/logs/container-*.log | head -10

# Read the most recent container log
cat groups/{group}/logs/container-{timestamp}.log

loginctl enable-linger

loginctl show-user $USER | grep Linger
# Expected: Linger=yes

-- The cursor is stored as a JSON object mapping JIDs to timestamps
SELECT value FROM router_state WHERE key = 'last_agent_timestamp';

# Rancher Desktop
rdctl set --kubernetes-enabled=false

# Then rebuild the container image
./container/build.sh

# Check k3s log for image GC activity (Rancher Desktop)
grep -i "nanoclaw" ~/Library/Logs/rancher-desktop/k3s.log
# Look for: "Removing image to free bytes" with the nanoclaw-agent image ID

# Check NanoClaw logs for image status
grep -E "image found|image NOT found|image missing" logs/nanoclaw.log

# Check for QR code requests
grep 'QR\|authentication required\|qr' logs/nanoclaw.log | tail -5

# Check auth files exist
ls -la store/auth/

claude
/add-whatsapp

# Check mount validation logs
grep -E 'Mount validated|Mount.*REJECTED|mount' logs/nanoclaw.log | tail -10

# Verify the mount allowlist is readable
cat ~/.config/nanoclaw/mount-allowlist.json

# Check group's container_config in DB
sqlite3 store/messages.db "SELECT name, container_config FROM registered_groups;"

# Check for failed IPC operations
ls -la data/ipc/errors/
cat data/ipc/errors/main-message-*.json

# Monitor IPC activity
grep 'IPC' logs/nanoclaw.log | tail -20

# Verify IPC directory permissions
ls -la data/ipc/main/
ls -la data/ipc/family-chat/

bash scripts/cleanup-sessions.sh --dry-run

Stale session detected — clearing for next retry

sqlite3 store/messages.db "DELETE FROM sessions WHERE group_folder = '{group-folder}';"

# Check for concurrent CLI processes
ls -la data/sessions/{group}/.claude/debug/

# Count unique SDK processes (each .txt file = one CLI subprocess)
# Multiple files = concurrent queries

# Check parentUuid branching in transcript
python3 -c "
import json, sys
lines = open('data/sessions/{group}/.claude/projects/-workspace-group/{session}.jsonl').read().strip().split('\n')
for i, line in enumerate(lines):
  try:
    d = json.loads(line)
    if d.get('type') == 'user' and d.get('message'):
      parent = d.get('parentUuid', 'ROOT')[:8]
      content = str(d['message'].get('content', ''))[:60]
      print(f'L{i+1} parent={parent} {content}')
  except: pass
"

launchctl kickstart -k gui/$(id -u)/com.nanoclaw

tail -f logs/nanoclaw.log

launchctl bootout gui/$(id -u)/com.nanoclaw

launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.nanoclaw.plist

npm run build && launchctl kickstart -k gui/$(id -u)/com.nanoclaw