Troubleshooting

Solutions to common issues during installation, configuration, and operation. If your problem isn’t listed here, check the GitHub Issues or open a new one.

Installation & Startup

Docker Compose fails to start

Symptom: docker compose up -d exits with errors.

Check the basics:

# Verify Docker is running
docker info

# Verify Compose is available
docker compose version

# Check which services failed
docker compose ps

Common causes:

JuiceFS mount fails

Symptom: The djinnbot-juicefs container keeps restarting or the API/engine can’t write to /jfs.

# Check JuiceFS container logs
docker logs djinnbot-juicefs

# Check if the mount succeeded
docker exec djinnbot-juicefs mountpoint -q /jfs && echo "Mounted" || echo "NOT mounted"

Common causes:

API server won’t start

Symptom: djinnbot-api container exits or health check fails.

docker logs djinnbot-api

Common causes:

Agent Containers

Agent container fails to start or times out

Symptom: Pipeline steps fail with container creation errors or timeout.

# Check engine logs
docker logs djinnbot-engine --tail 100

# Check if the agent runtime image exists
docker images | grep agent-runtime

Common causes:

Agent has no tools / MCP tools missing

Symptom: Agent output mentions it can’t find tools, or MCP tools don’t appear.

# Check mcpo health
curl http://localhost:8001/docs

# Check mcpo logs
docker logs djinnbot-mcpo

Fix: Ensure the mcp/config.json file exists and is valid JSON. The engine writes this file. If it’s missing, restart the engine: docker compose restart engine.

Authentication

Locked out — forgot password or lost 2FA

If you have database access:

# Connect to the database
docker exec -it djinnbot-postgres psql -U djinnbot -d djinnbot

# Disable 2FA for a user
UPDATE users SET totp_secret = NULL, totp_enabled = false WHERE email = 'your@email.com';

# Reset password (you'll need to use the API or re-run setup)

If you have the recovery codes from when you set up 2FA, use those at the login prompt. In the CLI, enter r at the TOTP prompt to use a recovery code.

“Unauthorized” on every API call

Performance

Agents are slow

High LLM costs

1. Check the Admin > API Usage dashboard for per-agent and per-model breakdowns
2. Use cheaper models for routine tasks (executor_model in the Plan+Execute pattern)
3. Enable PTC to reduce token usage
4. Use the Code Knowledge Graph instead of having agents read raw files
5. Set pulse_blackouts to prevent agents from running during off-hours
6. Lower max_wakes_per_day in agent coordination settings

Messaging Integrations

Slack bot not connecting

docker logs djinnbot-engine 2>&1 | grep -i slack

Discord bot fails to connect

Signal/WhatsApp not linking

Both use a shared phone number that must be linked:

1. Go to Settings > Integrations in the dashboard
2. Follow the linking flow (QR code for Signal, QR or pairing code for WhatsApp)
3. The link must be completed within the timeout window
4. Only one engine instance can run the Signal daemon at a time (distributed lock)

Data & Storage

Memory search returns no results

Lost data after restart

DjinnBot stores data in three places:

1. PostgreSQL — Docker volume postgres-data. Safe across restarts.
2. Redis — Docker volume redis-data with AOF persistence. Safe across restarts.
3. JuiceFS/RustFS — Docker volumes rustfs-data, juicefs-data, juicefs-cache. Safe across restarts.

Data is only lost if you run docker compose down -v (the -v flag deletes volumes). Never use -v unless you intend to delete all data.

Getting Help

If your issue isn’t covered here:

1. Check GitHub Issues for existing reports
2. Collect diagnostic info: docker compose ps, docker logs <container>, and your .env (redact secrets)
3. Open a new issue with the diagnostic info and steps to reproduce