Troubleshooting

etcd Bootstrap Failures

Symptom: etcd-bootstrap container exits with error

1. Check logs: docker logs etcd-bootstrap
2. Verify etcd is healthy: docker exec etcd etcdctl endpoint health
3. Ensure no port conflict on 2379: ss -tlnp | grep 2379
4. Restart the bootstrap job: docker-compose up -d etcd-bootstrap

Symptom: API server fails to start (“cannot connect to etcd”)

1. Verify etcd container is running: docker-compose ps etcd
2. Check etcd health: docker exec etcd etcdctl endpoint health
3. Ensure ETCD_HOST=etcd in .env (use the container name, not localhost)
4. Restart: docker-compose restart etcd && docker-compose up -d etcd-bootstrap

FalkorDB Connection Issues

Symptom: Health check shows falkordb: disconnected

1. Verify your FalkorDB instance is running and accessible from the Docker host
2. Check FALKORDB_HOST and FALKORDB_PORT in .env
3. If FalkorDB is on a remote host, ensure the Docker host can reach it:

   docker exec api python -c "import socket; s=socket.create_connection(('10.0.70.120',6397),5); print('OK')"

4. If using a password, verify FALKORDB_PASSWORD is set in etcd secrets (Admin UI)
5. Restart the API server: docker-compose restart api

Symptom: Knowledge graph operations fail silently

1. Check the API logs: docker-compose logs api | grep -i falkor
2. Verify the graph name matches: ensure KG_NAME in .env matches your FalkorDB graph
3. Check if schema indexes have been created: the first startup takes 7–10 minutes for production databases

Redis Connection Issues

Symptom: Workers fail to connect to Redis

1. Verify Redis is healthy: docker exec redis redis-cli -a redis123 ping
2. Check REDIS_HOST=redis in .env (use the container name)
3. If using a custom password, ensure REDIS_PASSWORD matches in all services
4. Restart workers: docker-compose restart rq-worker-1 rq-worker-2

Port Conflicts

Symptom: bind: address already in use

# Find what's using the port
ss -tlnp | grep :8000   # API
ss -tlnp | grep :6379   # Redis
ss -tlnp | grep :2379   # etcd
ss -tlnp | grep :80     # Gateway

Options:

• Stop the conflicting service
• Change the port mapping in docker-compose.yml (left side only):

  ports:
    - "8001:8000"  # Change host port from 8000 to 8001

Container Permission Issues

Symptom: Permission denied in worker or API logs

On Linux, the user directive in docker-compose.yml maps to ${UID:-1000}:${GID:-1000}:

1. Check your UID/GID: id
2. Ensure data directories are writable:

   sudo chown -R $(id -u):$(id -g) ./data ./logs ./ingestion_data ./extraction_data

3. Or set UID and GID in .env:

   UID=$(id -u)
   GID=$(id -g)

Stuck or Failed Ingestion Jobs

1. Check the RQ Dashboard at http://localhost:9181 for failed jobs
2. View worker logs: docker-compose logs rq-worker-1
3. Clear stuck sessions:

   docker exec api python scripts/fix_stuck_sessions.py

4. Restart workers: docker-compose restart rq-worker-1 rq-worker-2

Slow Startup

Symptom: API takes more than 15 minutes to become healthy

1. FalkorDB schema creation (133 indexes, 16 constraints) takes 7–10 minutes on first startup — this is expected
2. Check progress: docker-compose logs api | grep -i schema
3. If stuck, verify FalkorDB has sufficient memory (minimum 2 GB for production graphs)

Gateway Not Routing

Symptom: Admin UI or API unreachable through port 80

1. Verify all upstream services are running: docker-compose ps
2. Check gateway logs: docker-compose logs gateway
3. Verify nginx config: docker exec gateway nginx -t
4. Check that host.docker.internal resolves (Linux hosts — the compose file includes extra_hosts for this)

Getting Help

• Check the Health endpoint for component status
• Review container logs: docker-compose logs -f [service_name]
• Open an issue at github.com/nodekat/FluidRAG/issues