Error Messages Reference

A comprehensive dictionary of error codes, diagnostic causes, and verified solutions across the TurboV control plane and agent runtime.

Agent & Infrastructure Errors

AGENT_HEARTBEAT_TIMEOUT

  • Cause: The control plane has not received a WebSocket ping from the agent for over 60 seconds.
  • Diagnostics: 
    systemctl status turbov-agent
journalctl -u turbov-agent -n 50 --no-pager
  • Solution: Verify the host has outbound internet access. If the service crashed, restart with sudo systemctl restart turbov-agent.

PORT_CONFLICT_ERROR

  • Cause: Port 80 or 443 is already occupied by another daemon on the host (e.g. Apache2, Nginx, Caddy), preventing Traefik from binding.
  • Diagnostics: 
    sudo lsof -i :80
sudo lsof -i :443
  • Solution: Stop and disable the conflicting service: 
    sudo systemctl stop nginx && sudo systemctl disable nginx
sudo systemctl restart turbov-agent

DOCKER_DAEMON_UNREACHABLE

  • Cause: The agent cannot connect to the Docker daemon UNIX socket at /var/run/docker.sock.
  • Solution: Verify Docker service status and permissions: 
    sudo systemctl status docker
sudo systemctl start docker

Build & Deployment Errors

DOCKER_BUILD_FAILED

  • Cause: A command within the Dockerfile or Nixpacks build stage exited with a non-zero code (e.g. missing package, failed compilation).
  • Diagnostics: Open the Deployments tab in the dashboard and inspect the real-time build logs. Look for compiler or package manager errors (e.g. npm ERR!, tsc failed).
  • Solution: Resolve the syntax or dependency error locally and push a new commit.

DOCKERFILE_NOT_FOUND

  • Cause: Auto-detection was disabled or unable to identify the project runtime, and no file named Dockerfile was found in the configured root directory.
  • Solution: Ensure your Dockerfile is placed in the configured root directory or enable auto-detection in Application Settings → Build Method.

GIT_CLONE_FAILED

  • Cause: TurboV failed to clone the repository using the temporary GitHub App installation token.
  • Solution:
    1. Confirm the GitHub App has read access to the specific repository in your GitHub account settings.
    2. Confirm the branch exists in the remote repository.

HEALTHCHECK_TIMEOUT

  • Cause: The container started, but its HTTP health check endpoint did not return 200 OK within the configured timeout window (default: 60s).
  • Diagnostics: Inspect the container runtime logs via the dashboard or on the host: 
    docker logs <container_name> --tail 100
  • Solution: Ensure your application listens on 0.0.0.0 (all interfaces) rather than 127.0.0.1 (localhost only).

Database Errors

DATABASE_PROVISION_FAILED

  • Cause: The agent failed to launch the managed database container or initialize its persistent storage volume.
  • Diagnostics: Inspect agent logs on the host: 
    journalctl -u turbov-agent -g "DatabaseManager" -n 50
  • Solution: Verify that /var/lib/turbov/ has sufficient free disk space (df -h).

DATABASE_QUERY_TIMEOUT

  • Cause: A query executed inside Database Studio ran longer than the safety limit (30 seconds) or encountered a table lock.
  • Solution: Optimize the SQL query, add required indices, or specify an explicit LIMIT clause.

CLONE_JOB_FAILED

  • Cause: Database snapshot stream between source and target server was interrupted.
  • Solution: Ensure both source and target servers are ONLINE and have sufficient disk capacity to hold the uncompressed database dump.

Secrets & Security Errors

KMS_DECRYPTION_ERROR

  • Cause: The control plane failed to decrypt the environment Data Encryption Key (DEK) envelope.
  • Solution: Trigger a key re-verification in the application Security settings or re-save your environment variables.

BACKUP_STORAGE_UNREACHABLE

  • Cause: Direct-to-storage upload failed due to invalid S3 credentials, non-existent bucket, or clock skew.
  • Diagnostics: Inspect S3 storage settings in Settings → Backup Storage.
  • Solution: Verify your S3 Access Key, Secret Key, Bucket Name, and Region. For Cloudflare R2 or MinIO, verify the custom S3 endpoint URL.