Troubleshooting Guide

A practical troubleshooting guide for diagnosing and fixing issues across servers, containers, databases, and network routing in TurboV.

1. Server & Agent Issues

Server Shows as "Offline"

When a server is displayed as OFFLINE, the TurboV control plane has lost the outbound WebSocket heartbeat from the agent.

Verify Host Connectivity:

ssh root@your-server-ip
ping -c 3 1.1.1.1

Check Agent Service Status:

sudo systemctl status turbov-agent

If stopped or failed, inspect recent journal entries:

sudo journalctl -u turbov-agent -n 100 --no-pager

Restart the Agent:
```
sudo systemctl restart turbov-agent
```
Verify Local SQLite Database: The agent caches local state in /var/lib/turbov/agent.db. Verify database integrity:
```
sqlite3 /var/lib/turbov/agent.db "PRAGMA integrity_check;"
```

2. Reverse Proxy & Traefik Issues

Traefik Container Won't Start (Port Conflict)

Traefik requires binding to host ports 80 and 443. If an existing web server is running on the host, Traefik cannot launch:

# Check what is listening on port 80 and 443
sudo lsof -i :80
sudo lsof -i :443
 
# Common conflicting services: apache2, nginx, caddy
sudo systemctl stop nginx apache2 caddy
sudo systemctl disable nginx apache2 caddy
 
# Restart agent to re-trigger Traefik startup
sudo systemctl restart turbov-agent

Inspecting Traefik Logs & Configuration

The Traefik container runs under the name turbov-traefik:

# View live Traefik access and error logs
docker logs turbov-traefik -f --tail 100
 
# Inspect generated dynamic configuration files
ls -la /var/lib/turbov/traefik/dynamic/
cat /var/lib/turbov/traefik/dynamic/*.yml

SSL Certificate Stuck or Failing (Let's Encrypt)

If SSL certificates are not issuing:

Verify Port 80 is Reachable: Let's Encrypt uses the ACME HTTP-01 challenge, which requests a validation token over HTTP port 80. Ensure your firewall allows incoming traffic on port 80.
Verify DNS Propagation: Run dig +short A yourdomain.com from an external terminal to confirm your domain points directly to your server's public IP.
Check Cloudflare Proxy: If using Cloudflare DNS, temporarily set the proxy status to DNS Only (Grey Cloud) to allow Let's Encrypt validation.

Inspect ACME JSON Storage:

sudo ls -l /var/lib/turbov/traefik/acme.json
# Permissions must be strictly -rw------- (0600)

3. Deployment & Build Issues

Build Fails with "No Space Left on Device"

Docker images, builder caches, and orphaned layers can consume host disk space:

# Check disk usage
df -h
 
# Check Docker space breakdown
docker system df
 
# Prune unused images, build caches, and stopped containers safely
docker system prune -af --volumes

Build Fails or Gets Killed (Out of Memory)

If heavy compilation tasks (like next build or cargo build) trigger the Linux OOM killer:

Check Swap Status:
```
swapon --show
free -h
```

If swap is not enabled, enable it manually or verify that /swapfile exists:

sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab

Application Starts but Cannot Be Reached (Host vs Localhost)

If your container is running according to docker ps, but requests return 502 Bad Gateway:

Common Cause: The application server inside the container is listening on 127.0.0.1 (localhost only) instead of 0.0.0.0 (all interfaces).
Fix: Configure your web framework (Express, Fastify, Next.js, Uvicorn, Gin) to bind to host 0.0.0.0. In Next.js, run next start -H 0.0.0.0.

4. Managed Database Issues

Application Cannot Connect to Managed Database

Internal Docker Network: Ensure your application environment and the database are on the same server, or that you are using the internal Docker hostname (e.g. db-postgres:5432) rather than localhost:5432.
Database Status: Confirm the database container is healthy:
```
docker ps --filter "name=db-"
```

Still Need Help?

Search our Error Messages Reference for specific error codes.
Review our Frequently Asked Questions.
Open an issue on GitHub with your agent logs (journalctl -u turbov-agent -n 100) and system details.