Operations

Troubleshooting

Fixes for offline agents, failed deploys, certificates and email.

A server shows offline

A server is offline when no heartbeat arrived in 35 seconds. On the server:

bash

systemctl status vpspilot-agent vpspilot-helperjournalctl -u vpspilot-agent -n 100sudo -u vpspilot python3 -m vpspilot_agent status --config /etc/vpspilot/agent.json

Connection refused or timeouts: the server can’t reach AGENT_API_URL. Check DNS, firewalls and that the proxy routes /agent/* to the API.
Agent exited with status 78: its credential was revoked or the server deleted. Enroll it again with a new token.
Clock skew: keep time in sync with systemd-timesyncd or chrony.

The control plane installer fails

Message	Fix
Port 80 (or 443) is in use	Another web server holds it. See nginx or Apache already running.
The API didn't come up	Read `sudo vpspilot logs api`. Re-running the installer is safe.
The dashboard has no certificate	DNS for the domain must point at this server, and ports 80/443 must be open in your provider's firewall.

The agent installer fails

Message	Fix
Enrollment token is invalid or already used	Tokens are single use. Create a new enrollment.
Enrollment token has expired	Tokens last 15 minutes. Create a new one and run the command right away.
Unsupported OS	Only Ubuntu and Debian are supported.
Run as root	Pipe into `sudo bash`, as in the generated command.

A deployment failed

Open the deployment: the log shows the stage that failed.

Symptom	Likely cause
Docker isn't installed on this server	Install Docker Engine, for example with `apt install docker.io`, then redeploy.
No Dockerfile, and this doesn't look like…	Add a Dockerfile, set build and start commands, or deploy an image.
Health check failed after 60s	The app isn't listening on the container port, binds to 127.0.0.1 instead of 0.0.0.0, or the health path returns 4xx/5xx.
The container exited	The process crashed on start. The log includes the container's last output.
Port … is already used by the container …	Another container holds the host port. Pick another port in the app's settings, or stop that container.
connection to server at "localhost" … refused	Inside a container, `localhost` is the container. Point the app at a managed database (`vpdb-<name>`) or run it as a systemd app.
does it listen on $PORT? (systemd apps)	The app must listen on `$PORT` on `0.0.0.0`.
Service … uses privileged mode (Compose)	The compose file uses a setting VPSPilot refuses. See Applications → Compose apps.
No space left on device	Check `df -h` and `docker system df`. Remove old images with `docker image prune`; agents 1.1.0+ clean up after failed deployments.

Tip

Most frameworks listen on PORT. Make sure yours binds to 0.0.0.0, not localhost, inside the container.

A certificate isn’t issued

DNS status must be ok. Behind a CDN proxy, use TLS mode off and let the CDN terminate TLS.
Ports 80 and 443 must be open in the server’s firewall and your provider’s security group.
Check the proxy’s own log with docker logs vpspilot-proxy.

Emails don’t arrive

Without RESEND_API_KEY, emails are written to the API log instead of being sent (sudo vpspilot logs api). After adding the key to .env, run sudo vpspilot restart.
Resend’s test sender only delivers to your own Resend account address. Set EMAIL_OVERRIDE_TO to it while testing, or verify a domain and set EMAIL_FROM.

Locked out

After 5 wrong passwords the account is locked for 15 minutes. If you lost your authenticator, sign in with a recovery code. If you have neither, someone with root on the control plane's server can create a new admin with sudo vpspilot admin EMAIL (or uv run poe createadmin on a manual install).