Troubleshooting

Common issues and how to resolve them.

Gateway Not Connecting

Symptom: Gateway status shows "Disconnected" in the dashboard header.

Causes and fixes:

1. Gateway container not running

   docker compose ps gateway
   # If not running:
   docker compose up -d gateway

2. Gateway token mismatch Verify GATEWAY_TOKEN in .env matches what the gateway expects:

   grep GATEWAY_TOKEN .env
   docker compose logs gateway | grep "token"

3. AI model API key invalid The gateway connects to your AI provider on startup. If the API key is wrong:

   docker compose logs gateway | grep -i "error\|auth\|key"

   Fix the MODEL_API_KEY in .env and restart: docker compose restart gateway

4. Port conflict Check if port 18789 is in use:

   ss -tlnp | grep 18789

Agent Not Responding

Symptom: You click Execute but nothing happens, or the task stays in "In Progress" indefinitely.

1. Check gateway connection — the gateway must be connected (see above)

2. Check agent status — the agent should show as "Online"

   docker compose logs backend | grep "agent" | tail -20

3. Check for errors — look at both backend and gateway logs:

   docker compose logs backend --tail 50
   docker compose logs gateway --tail 50

4. AI provider rate limit — your provider may be throttling requests. Check the gateway logs for rate limit errors.

5. Restart the gateway:

   docker compose restart gateway

Cannot Log In

Symptom: Login page returns "Invalid credentials" even with correct password.

1. Check email format — use the exact email from setup (case-sensitive)

2. Reset password via CLI:

   helix reset-password admin@company.com

3. Check backend is running:

   docker compose ps backend
   curl http://localhost:8000/api/health

4. Check database connection:

   docker compose logs backend | grep -i "database\|postgres\|connection"

Database Connection Errors

Symptom: Backend logs show database connection errors.

1. Check PostgreSQL is running:

   docker compose ps db
   docker compose logs db --tail 20

2. Verify DATABASE_URL:

   grep DATABASE_URL .env

   Format: postgresql+asyncpg://user:password@db:5432/helix_mc

3. Check disk space — PostgreSQL needs free disk:

   df -h

4. Restart database:

   docker compose restart db
   # Wait for it to be healthy, then restart backend
   docker compose restart backend

Migration Errors

Symptom: Backend fails to start with Alembic migration errors.

1. Check current migration state:

   docker compose exec backend alembic current

2. Run pending migrations:

   docker compose exec backend alembic upgrade head

3. If migrations are corrupted, restore from backup:

   helix restore backups/latest-backup.sql.gz

SSL Certificate Issues

Symptom: Browser shows SSL errors or certificate warnings.

1. Check Caddy logs:

   docker compose logs caddy --tail 50

2. DNS not pointing to server — verify your domain points to your server's IP:

   dig +short your-domain.com

3. Port 80/443 blocked — Let's Encrypt needs port 80 for validation:

   sudo ufw status
   # Ensure ports 80 and 443 are allowed

4. Force certificate renewal:

   docker compose restart caddy

Frontend Not Loading

Symptom: Blank page or "Cannot connect" error.

1. Check frontend container:

   docker compose ps frontend
   docker compose logs frontend --tail 20

2. API URL mismatch — NEXT_PUBLIC_API_URL must be accessible from the browser:

   grep NEXT_PUBLIC_API_URL .env

   If changed, rebuild: docker compose up -d --build frontend

3. CORS error — check browser console for CORS errors:

   grep CORS_ORIGINS .env
   # Must include the frontend's URL

High Memory Usage

Symptom: Server is slow or services are being killed.

1. Check memory usage:

   docker stats --no-stream
   free -h

2. Reduce memory — if running on a small server:

   • Set LOG_LEVEL=warning to reduce log volume
   • Consider using a smaller AI model

3. Check for runaway processes:

   top -o %MEM

Telegram Bot Not Working

See the Telegram troubleshooting section.

Getting Help

If none of these solutions work:

1. Collect diagnostics:

   helix health > health-report.txt
   docker compose logs > docker-logs.txt 2>&1

2. Check the logs for specific error messages:

   docker compose logs --tail 200 2>&1 | grep -i error

3. Contact support at helixnode.tech with your health report and logs.

Log Locations Quick Reference

Log	Command
All services	docker compose logs
Backend	docker compose logs backend
Frontend	docker compose logs frontend
Gateway	docker compose logs gateway
Database	docker compose logs db
Redis	docker compose logs redis
Caddy	docker compose logs caddy
Systemd	journalctl -u helix-mission-control