Troubleshooting

Start with the doctor command for the layer that failed, then read the daemon log. Most failures are a missing token, a closed port, or DNS that does not point at the server yet.

The CLI cannot connect

$ vxl server ls
$ vxl server inspect prod
$ vxl doctor remote --server prod

On the server:

$ sudo systemctl status voxeltrond
$ sudo journalctl -u voxeltrond -n 100 --no-pager
$ ss -ltnp | grep 50051

Check three things:

  • The profile has the current operator token. vxl server inspect shows the host and transport.
  • SSH to the server works with the same user and key.
  • The daemon is listening on 127.0.0.1:50051. It does not need a public listener.

A deployment fails

$ vxl app list --server prod
$ vxl deploy status --name api --server prod
$ vxl deploy logs --deployment-id <deployment-id> --server prod
$ vxl doctor app --name api --server prod

For a manifest, run vxl up --dry-run first. It catches an invalid manifest without contacting the daemon. A blank product key, more than one app source, or an unsupported service type is rejected before any RPC.

For a source build, check that the daemon can reach the registry or git host. For an image deploy, check the image reference and pull policy. vxl doctor container shows whether the container is running and how it is isolated.

A failure that starts with VXL-CAP-001 means the image needs root capabilities. See Image needs root capabilities, or runvxl app fix in the app's directory for a fix plan.

The domain does not get a certificate

$ vxl doctor route --server prod --deployment-id <deployment-id> --public-url https://api.example.com/healthz
$ vxl doctor remote --server prod --domain api.example.com
$ sudo journalctl -u voxeltrond | grep -i -E 'acme|cert|tls|challenge'

Confirm:

  • An A record for the hostname points at the server.
  • Port 80 is reachable from the internet for the HTTP challenge.
  • proxy.acme.email is set in the daemon configuration.
  • The deploy used the Caddy edge, not Cloudflare by accident.

A deploy with a domain and no ACME email fails with an error namingproxy.acme.email. Fix the configuration and redeploy rather than falling back to a private domain.

A database command fails

$ vxl db list --server prod
$ sudo journalctl -u voxeltrond -n 200 --no-pager

Database calls are scoped to a project. If the daemon rejects the call with a project authorization error, create the database with the correct --project, or check that the operator token belongs to an operator for that project.

A backup upload fails

The local dump is written before the upload. A failed upload therefore leaves a local copy.

  • Check AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY in the daemon environment.
  • Check that the bucket exists and the key can write to the prefix.
  • For MinIO or another S3-compatible service, set endpoint.
$ sudo systemctl show voxeltrond --property=Environment
$ sudo journalctl -u voxeltrond -n 200 --no-pager | grep -i -E 's3|backup|upload'

The command output never prints secret values. If a key appears in a log line, treat it as exposed and rotate it.

Configuration does not load

$ sudo voxeltrond config validate
$ sudo voxeltrond config render --runtime docker

Render a fresh file and compare it with the active one. A missing required section or an unknown key in a strict section is rejected at load. Seeconfiguration.

Collect evidence for a report

$ vxl --version
$ voxeltrond --version
$ vxl doctor remote --server prod --json
$ sudo journalctl -u voxeltrond -n 300 --no-pager

Redact tokens, connection strings and secret values before posting logs. Seesupport.

HTTP 404 with No app is deployed at this address. means no app route matches this host, including after vxl down.