Troubleshooting

Common problems, what causes them and how to fix them. Most answers start in the same place: the service's Logs, which have the build output and the app's own output (Logs).

Servers

Setup fails to connect

• Connection timed out or refused: the SSH port is closed in the cloud provider's firewall or security group, or the address or port is wrong. Allow the SSH port from anywhere while setup runs; you can close it afterwards (Requirements).
• Authentication failed: check the SSH user. Cloud images often disable root login; use ubuntu, debian or ec2-user. A key must be the private key, not the .pub file, and without a passphrase (Add a Server).
• sudo asks for a password: the user needs passwordless sudo, or connect as root.
• Host key changed: Zenavo refuses to connect when the server's fingerprint differs from the first setup. If you reinstalled the machine on purpose, remove the server and add it again; otherwise find out why before going on.

Setup fails while installing

Read the last lines of the setup log on the server's Status tab. Common causes:

• Ports 80 or 443 are taken by Docker, Nginx, Apache or another web server. The server should be dedicated to Zenavo; stop and disable them, then Retry setup.
• Not enough memory or disk: at least 2 GB of memory and 20 GB of free disk (Requirements).
• Downloads time out in mainland China: the log shows which sources setup chose (Servers in mainland China).
• The agent never connects: the server needs outbound HTTPS (port 443) to the Zenavo console.

Retrying skips the steps that finished.

A server shows Offline

Zenavo has not heard from the server's agent for a few minutes. Projects on it keep running; only deployments and live data pause. Check that the machine is on, has outbound HTTPS, and is not out of memory or disk. When the agent is back, the status returns to Running on its own. If it does not, Settings → Run setup reinstalls the agent without touching what runs (Manage a Server).

Builds

Zenavo detected the wrong language or no plan

zbpack looks at the files in the root directory. In a monorepo, set Root directory to the app's folder. Add a Dockerfile to control the build entirely, or set zbpack options such as ZBPACK_BUILD_COMMAND and ZBPACK_START_COMMAND (Build Plan).

The build fails

Open Logs → Build Logs. The last error is usually the reason: a missing dependency, a failing build script, or a value the build needs. Variables on the Variables tab are not passed to the build by themselves: reference the ones it needs as build arguments. Try the same build locally with docker build . to tell an app problem from a platform one.

The build waits or stops

• Waiting for a build machine: your plan's builds at a time are in use, or the shared build machines are busy (Build queue).
• Timed out: builds stop after the plan's longest build time (Usage & Billing).
• Refused: the workspace used its build minutes for the month. Deploying prebuilt images keeps working.

Deploys

The deploy never becomes healthy

The new instance started but never passed its health check; the old instance keeps serving. Usually:

• The app listens on localhost or a fixed port. Listen on 0.0.0.0 and on the PORT variable (Frameworks).
• The port is wrong. The service's port under Networking must be the one the app listens on.
• The health check path returns 404, or the app needs longer to start. Fix the path or raise the start period.

The failed deploy shows the reason from the last check and the instance's latest logs.

The service keeps crashing or was suspended

The container exits right after it starts. Read Logs for the error: a missing variable, a database it can't reach, or a crash on start. A service killed for using too much memory restarts too: raise its memory limit (Service Settings). After the number of restarts set as its crash limit, Zenavo suspends the service; fix the cause, then resume it or deploy again.

Deploys are refused because of image transfer

The workspace reached its spending limit, or used the image transfer a Free plan includes. Running services keep running. Raise the limit or upgrade the plan (Image Transfer & Spending Limit).

A service can't reach another service

Use the other service's private hostname, <hostname>.zenavo.internal, and the port it listens on, not its public domain or localhost. Both services must be in the same project. The other service's Networking tab shows the address under Private (Private Networking).

Domains and HTTPS

The certificate stays Pending

Let's Encrypt has not been able to check the domain yet. Hover over Pending on the service's Overview for the reason. Usually:

• The DNS record does not point at the server yet. Check it with dig +short app.example.com; it should print the server's IP address. New records can take a while to spread.
• Port 80 is closed. Let's Encrypt checks the domain over HTTP.
• Cloudflare's proxy is on with SSL set to Flexible. Set it to Full (strict), or turn the proxy off until the certificate is issued.

The state refreshes about once a minute (Domains & HTTPS).

The domain shows 404 or an error page

• 404 page not found: the domain reaches the server but no service has it. Bind it under the service's Networking tab.
• Bad gateway or Service unavailable: the domain is bound, but the service is not running, or it listens on another port than the one the domain routes to.

Account and access

I can't add a server or deploy

Verify your email first: open the link Zenavo emailed you, or send a new one from Account settings (Your Account). Viewers can't deploy or change anything; ask a team admin for the member role (Teams & Roles).

I lost my two-factor device

Sign in with a recovery code (Two-Factor Authentication). Without one, contact info@zenavo.app from the account's email address.

Still stuck?

Email info@zenavo.app with the project or server ID (copy it from Settings), the time it happened, and what the logs show. Never send passwords, keys or variable values.