Troubleshooting
Start with the app’s Overview tab: its diagnosis names the problem in plain words and often has a fix button. The build log (Source → Builds) and the Logs tab have the details.
Deploys
Section titled “Deploys”| What you see | What to do |
|---|---|
| App never started listening | Listen on the PORT variable, on 0.0.0.0, not localhost or 127.0.0.1. |
| Warning that the app listens on another port, with Use port N | Click it, or set Settings → Container port. |
| last deploy failed: …, old version still running | The new version didn’t become ready within 60 seconds, or failed its health path. Check its logs; the old version keeps serving. |
App connects to localhost:5432 (or 6379) and fails |
Services run in their own containers. Use DATABASE_URL (or the injected variables), not localhost. |
| Build fails | Read the build log. Without a Dockerfile, Nixpacks guesses from your files: add a Dockerfile to take control. Builds stop after 20 minutes. |
creating: pulling <image> for a long time |
Large images (Immich, Home Assistant) can take many minutes on the first deploy. A pull gives up after 45 minutes. |
| Quota exceeded, nothing deployed | The deploy would go over your workspace or plan limits. Lower memory or replicas, remove something, or raise the limit. |
| Not deployed (unresolved references) | A ${node.field} points at a node that isn’t linked, or a field that doesn’t exist. Link the node or fix the name. |
| won’t deploy: … in the plan | The reason is shown next to the item. Fix it, or discard that change and deploy the rest. |
| “are in different networks” when linking | Move both nodes into the same group. |
| A variable from a link is missing | Links apply at the next deploy. Make sure the link isn’t still staged, then redeploy the app. A value you set by hand under the same name wins over the link. |
Websites
Section titled “Websites”| What you see | What to do |
|---|---|
| No address | The node is Private. Switch Visibility to Public, or link a Domain. |
400 Bad Request, redirect loop, or http:// links |
The app doesn’t trust the proxy: see Apps behind the proxy. |
| Custom domain says not verified | Check the TXT and CNAME (or A) records against the panel, wait for DNS to update, then Verify domains. |
| Custom domain stopped working | DNS no longer points at ZedCloud, so the route was removed. Fix the records and press Verify. |
| Waking |
The app was asleep. It reloads by itself; turn on Keep awake to avoid it. |
| What you see | What to do |
|---|---|
| Cache is empty after a restart | Valkey keeps data in memory. Store anything you can’t lose in a database. |
| Node stopped for disk usage | It went more than 10% over its volume limit. Raise volumeSizeMB or delete data, then start it. |
| Can’t connect from my laptop | Turn on External access, add your current IP, use a non-root account and TLS (sslmode=require, rediss://). |
Object storage NoSuchBucket or signature errors |
Use path-style addressing (forcePathStyle: true). |
Linux boxes
Section titled “Linux boxes”See Private networks → Troubleshooting and Linux boxes.
Still stuck? Ask an AI agent connected through MCP to read the diagnosis and logs, or contact support with the node’s ID.