Troubleshooting

Worker won’t start

# Check gateway logs first (it launches worker containers on demand)
docker compose -f docker/docker-compose.yml logs -f gateway

# List spawned worker containers
# (the compose `worker` service only builds the image; it does not stay running)
docker ps --format '{{.Names}}' | grep lobu-worker || true

# Common causes:
# - Port 8080 already in use → Change GATEWAY_PORT in .env
# - Docker network conflict → docker compose down -v && docker compose up -d
# - Invalid lobu.toml → npx @lobu/cli@latest validate

Agent not responding

# Check if gateway is running
curl http://localhost:8080/health

# Check Redis connection
docker compose -f docker/docker-compose.yml exec redis redis-cli ping

# Clear stale chat history (for stuck conversations)
docker compose -f docker/docker-compose.yml exec redis redis-cli KEYS 'chat:history:*'
docker compose -f docker/docker-compose.yml exec redis redis-cli DEL 'chat:history:{key}'

# Recreate gateway after .env changes
# (`restart` does not reload env-file values)
docker compose -f docker/docker-compose.yml up -d --force-recreate gateway

MCP tools failing

# Check MCP status at /api/docs on your gateway
# Verify worker can reach gateway
docker compose -f docker/docker-compose.yml exec worker curl -v http://gateway:8080/health

# For OAuth flows: check browser console and gateway logs
# For static headers: verify ${env:VAR} syntax in mcpServers config

Platform connection issues

Platform connections are usually configured from the Connections UI or the /api/v1/connections API, not by editing per-platform env vars in docker-compose.yml.

Slack: Reconnect or reinstall the workspace after adding scopes. If you use Slack OAuth install flows on a self-hosted gateway, also verify SLACK_CLIENT_ID and SLACK_CLIENT_SECRET on the gateway.

Telegram: Verify the bot token and webhook / polling settings in the connection config. Webhook mode still needs a public HTTPS URL.

Discord: Verify the bot token, configured intents, and guild ID in the connection settings.

WhatsApp: Confirm the configured phone number is verified in Meta and matches the connection settings.

Network policy blocking requests

# Check what domains are allowed
echo $WORKER_ALLOWED_DOMAINS

# Temporarily allow all (for testing only)
export WORKER_ALLOWED_DOMAINS="*"
docker compose -f docker/docker-compose.yml restart gateway

# Proper format: exact domain or .wildcard
# api.example.com  - only this domain
# .example.com     - all subdomains

Worker can’t reach the internet

By design, workers have no direct internet access. All traffic routes through the gateway proxy.

# Verify proxy is reachable
docker compose -f docker/docker-compose.yml exec worker curl -v http://gateway:8118

# Check if domain is in allowlist
# See "Network policy blocking requests" above

Out of memory / disk space

# Check worker stats
docker stats

# Clean up old workspaces (Docker)
docker compose -f docker/docker-compose.yml down -v
rm -rf workspaces/*

# For K8s: check PVC usage
kubectl get pvc -n lobu
kubectl describe pvc <pvc-name> -n lobu

Owletto connection issues

# Verify local Owletto is running (if you're using owletto-local)
curl http://localhost:8787/health

# Check file-first memory config
# - lobu.toml should contain [memory.owletto] with enabled = true and an org
# - MEMORY_URL is optional; use it mainly for local/custom Owletto base URLs

# Test connection
npx owletto@latest health

Slow responses

# Check trace ID in logs (format: tr-xxx-lx4k-xxx)
# Use with Grafana Tempo or OTLP collector

# Common causes:
# - Cold worker start → Subsequent requests are faster
# - Model latency → Try a different provider/model
# - Large prompt context → Clear chat history or increase context window

Docker-specific issues

# Clean restart
docker compose -f docker/docker-compose.yml down -v
docker system prune -f
docker compose -f docker/docker-compose.yml up -d

# Rebuild worker image after code changes
make clean-workers  # or: docker compose -f docker/docker-compose.yml build --no-cache worker

Kubernetes-specific issues

# Check pod status
kubectl get pods -n lobu
kubectl describe pod <pod-name> -n lobu

# Worker not scaling?
# Check if HPA is hitting min/max replicas
kubectl get hpa -n lobu

# PVC stuck in Terminating?
kubectl patch pvc <pvc-name> -n lobu -p '{"metadata":{"finalizers":null}}'

Still stuck?

1. Enable verbose logging: LOG_LEVEL=debug in .env
2. Collect logs with trace ID
3. Open an issue at github.com/lobu-ai/lobu