Troubleshooting

Docker not found

ERROR: Docker is not installed.

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

Docker daemon not running

ERROR: Docker daemon is not running.

sudo systemctl start docker

Permission denied on Docker socket

Got permission denied while trying to connect to the Docker daemon socket

Add your user to the docker group:

sudo usermod -aG docker $USER
# Log out and back in

Worker can't enroll

1. Verify the master is reachable from the worker at CONTEXTBAY_MASTER_URL over plain HTTP (the one-time /api/enroll call happens before the mesh is up):

   curl -v $CONTEXTBAY_MASTER_URL/api/health

2. Open the Hosts page in the master UI and check the recent enroll-attempts log for this host — each attempt is tagged with a reason code (bad_secret, invalid_token, expired, already_consumed, rate_limited, not_configured, mesh_mint_failed) so you can see exactly why it was rejected.
3. Tokens are short-lived (~24h). If the worker took longer than the token TTL to start, click Regenerate token and re-run the install snippet.
4. Confirm CONTEXTBAY_SHARED_SECRET on the worker matches [mesh].shared_secret on the master (rejection reason bad_secret).

Worker enrolled, gRPC won't connect

1. After enrollment all gRPC traffic flows over Headscale on the address in CONTEXTBAY_MASTER_ADDR (typically <MASTER_MESH_IP>:7481). The worker uses an embedded tsnet client — there is no tailscale CLI inside the container. Check mesh state from the master UI instead.

   <MASTER_MESH_IP> is the master's address on the Headscale mesh, in the 100.64.0.0/10 CGNAT range — the master is always assigned 100.64.0.1, so the shape is the same on every install.

2. Open Settings → Mesh in the master UI, or call GET /api/mesh/status and GET /api/mesh/nodes. A worker that finished enroll but can't dial gRPC will show up as a mesh node but no heartbeat.
3. If you're on a single-node dev install with mesh.mode = direct, set CONTEXTBAY_MASTER_ADDR on the worker to the master's LAN address (this mode is dev-only).

Web UI not loading

1. Check the master is running:

   docker logs contextbay

2. Verify port 7480 is not in use:

   ss -tlnp | grep 7480

3. Try the health endpoint:

   curl http://localhost:7480/api/health

SQLite locked

database is locked

Ensure only one master instance runs per database file. ContextBay uses WAL mode to minimize locking, but concurrent access from multiple processes is not supported.

Migration errors

1. Check logs for the specific error
2. Back up your database file
3. The migration system tracks applied migrations and will retry failed ones on next startup

Discord bot not responding

1. Verify discord.enabled = true in config
2. Verify bot token is valid and Message Content Intent is enabled in the Developer Portal
3. Verify guild_id matches your Discord server
4. Check master logs for Discord-related errors

Ollama (cb-ollama) AI not responding

1. Check that the cb-ollama sub-container is healthy:

   curl http://cb-ollama:11434/api/tags
   # or via the master UI: Admin -> Sub-containers -> cb-ollama

2. For an external Ollama, override CONTEXTBAY_AI_OLLAMA_ENDPOINTS with a comma-separated list of full URLs (including http://).

RAG search returns no results on a fresh deploy

cb-ollama auto-pulls the embedding model on first boot. Until the pull finishes the index is empty — wait for the master log line:

ollama bootstrap: model ready model=nomic-embed-text

Then trigger a re-index from Knowledge → Settings → Re-index.

Model not found

The default Ollama chat model is llama3:8b (configurable via [ai].default_model). Pull it (or your override) on the cb-ollama instance:

docker exec cb-ollama ollama pull llama3:8b

n8n logs show 403 on /api/v1/variables

Expected on community / free n8n. The Variables endpoint is an enterprise-only feature; CB detects this and gracefully skips variable sync. Everything else (workflows, credentials, webhooks) keeps working.

Master crashes on startup after wiping only one volume

The three CB volumes form a chain (contextbay-data,contextbay-portainer-data,cb-n8n_contextbay-n8n-data). Removing one in isolation leaves the others with stale credentials. For a fresh install, wipe all three together.

High memory usage

• Reduce the number of metrics retained with shorter retention periods
• Use PostgreSQL instead of SQLite for large deployments
• Reduce the number of concurrent AI tasks

Slow dashboard loading

• Reduce the time range on time series panels
• Limit the number of panels per dashboard
• Ensure metrics queries include a node_id filter