Common Errors

Startup errors

Port 18781 already in use

Another process is using the API port.

# Find what's using it
lsof -i :18781

# Stop the conflicting process, or use a different port
snippbot start --port 19000

Python 3.11+ required, found 3.10.x

Your active Python is too old.

# Check what's being used
which python3 && python3 --version

# Install Python 3.11+ and ensure it's on PATH, or activate the venv
source .venv/bin/activate

ModuleNotFoundError: No module named 'snippbot_core'

The Python packages aren’t installed, or the venv isn’t activated.

source .venv/bin/activate
pip install -e packages/core packages/local packages/cli

ANTHROPIC_API_KEY is not set

No AI provider is configured.

snippbot config set anthropic_api_key sk-ant-your-key
# or
export ANTHROPIC_API_KEY=sk-ant-your-key

---

Auth errors

401 Unauthorized

Your token is missing, expired, or invalid.

# Verify your API key works
curl http://localhost:18781/api/auth/validate \
  -H "Authorization: Bearer snip_your_key"

# Create a new API key via Settings → API Keys in the UI

403 Forbidden

Your token is valid, but your permission level is insufficient for this action.

Check the operation’s required permission level in Settings > Security.

Setup already complete — cannot re-register

The POST /api/auth/register endpoint only works when zero users exist.

# To reset and start fresh (creates a backup first)
snippbot reset --soft    # re-run setup wizard
snippbot reset           # full reset

---

Task execution errors

Task stuck in running state

The executor may have crashed mid-task.

# Restart the daemon
snippbot stop && snippbot start

# The task will be retried on next startup

Task timeout after 300s

The task exceeded the default 5-minute timeout.

Increase the timeout for long-running tasks via the API or increase the global default:

SNIPPBOT_TASK_TIMEOUT=1800 snippbot start   # 30 minutes

Rate limit exceeded (transient failure)

The AI provider returned a 429. Snippbot will automatically retry with exponential backoff. No action needed unless it persists.

Agent workspace not found

The agent’s workspace directory was deleted or is inaccessible.

# Check workspace exists
ls -la ~/.snippbot/workspaces/

# Recreate if missing — daemon will reinitialize on next task
mkdir -p ~/.snippbot/workspaces/

---

Browser automation errors

Chrome not found

Browser automation requires Chrome or Chromium.

# macOS
brew install --cask google-chrome

# Ubuntu/Debian
apt-get install -y chromium-browser

# Or specify path
SNIPPBOT_CHROME_PATH=/usr/bin/chromium snippbot start

CDP connection refused

The browser process crashed or wasn’t started.

# Enable browser debug logging
SNIPPBOT_LOG_LEVEL=debug snippbot start
tail -f ~/.snippbot/logs/daemon.log | grep browser

---

Sandbox errors

Docker not found

Sandbox execution requires Docker or Podman.

# Install Docker
# https://docs.docker.com/engine/install/

# Or use process-based sandbox (no isolation)
SNIPPBOT_SANDBOX_BACKEND=process snippbot start

Container failed to start

Docker daemon may not be running.

# macOS
open -a Docker

# Linux
sudo systemctl start docker

---

Database errors

database is locked

Another process has the SQLite database open.

# Stop all running instances
snippbot stop --force

# Check for zombie processes
pgrep -f snippbot
kill <pid>

disk I/O error or no such table

Database corruption or migration needed.

# Run health check
snippbot doctor

# Last resort: reset (backup is created first)
snippbot reset

---

Channel adapter errors

Webhook signature verification failed

The signing secret doesn’t match what the platform sends.

• Re-check the signing secret in Settings → Channels
• Ensure the webhook URL is correct (Snippbot’s public URL on port 18790)

Adapter server not reachable from internet

Webhooks require a publicly accessible URL. In development, use a tunnel:

# ngrok (free tier)
ngrok http 18790

# cloudflared tunnel
cloudflared tunnel --url http://localhost:18790

---

Getting more help

snippbot doctor          # Automated health check
snippbot doctor --fix    # Try auto-fixes

tail -f ~/.snippbot/logs/daemon.log   # Live logs

See also: Debug Guide and FAQ.