Troubleshooting

Build failures

Dependency install fails

Symptoms: Build log shows npm ERR!, yarn ERR!, or similar during the install step.

Common causes and fixes:

Cause	Fix
Missing package-lock.json	Commit your lockfile — don’t .gitignore it
Private package registry	Add registry credentials as environment variables
Incompatible Node version	Add a .node-version or .nvmrc file to pin the Node version
Wrong root directory	Check Settings → Root directory if your package.json is in a subdirectory

Build command fails

Symptoms: Command failed error after dependencies install.

Common causes and fixes:

Cause	Fix
Wrong build command	Check Settings → Build command (e.g., npm run build)
Missing environment variable at build time	Add the required env var in Settings → Environment Variables
TypeScript errors	Fix type errors — tsc --noEmit should pass locally
Out-of-memory during build	Upgrade your plan for more RAM

Framework not detected

If Zanode picks the wrong framework or shows “Other”, go to Settings → Framework and manually select the correct one, or override the build/start commands directly.

---

Runtime / crash loop

A crash loop is when your container starts, crashes, and immediately restarts in a cycle. The Logs tab shows a warning banner when this is detected.

Port already in use (EADDRINUSE)

Your app is trying to bind to a port that is already occupied.

Fix: Ensure your app listens on the port Zanode expects. For most frameworks this is 3000. You can also set a custom port in New Project → Advanced Options → App port (for Dockerfile projects).

// Express example — read port from environment
const port = process.env.PORT || 3000;
app.listen(port, '0.0.0.0');

Missing module (MODULE_NOT_FOUND)

Symptoms: Cannot find module '...' at startup.

Common causes and fixes:

Cause	Fix
Module not in dependencies (only devDependencies)	Move it to dependencies in package.json
Output directory doesn’t include node_modules	Check your build command copies all required files
Wrong start command path	Confirm the file exists in the output directory

Missing file or directory (ENOENT)

Your start command references a file that doesn’t exist after the build.

Fix: Verify your output directory in Settings matches where your build puts artifacts. For example, SvelteKit builds to build/, Next.js to .next/.

Missing environment variables

Symptoms: Logs show undefined, process.env.X is undefined, or similar.

Fix: Add the missing variable in Settings → Environment Variables. Remember to redeploy after adding env vars — they take effect on the next deploy.

---

Logs say “No logs available”

Your app is not running. Common causes:

1. First deploy hasn’t happened yet — Go to the project header and click deploy
2. Container failed to start — Check the Deployments tab for the build log and look for errors
3. App was stopped — From the Overview, click restart application in Quick actions

---

Database connection issues

Cannot connect to PostgreSQL

Symptom	Fix
Connection refused	Confirm the database is in the same project and its status is running
SSL error with older clients	Remove sslnegotiation=direct from the connection string (requires psql 17+) — see Managed PostgreSQL
Connection string not set	Add DATABASE_URL as an environment variable in Settings
Authentication failed	Verify the password from the database card on the Databases tab

---

Custom domain not working

Symptom	Fix
DNS not resolving	Check your CNAME record points to the value shown in the dashboard
SSL certificate pending	Wait up to 5 minutes after DNS propagates, then refresh
Mixed content warnings	Ensure your app is not hardcoding http:// URLs internally

See Custom domains for the full setup guide.

---

Deployment stuck in “queued” or “building”

If a deployment is stuck for more than 10 minutes:

1. Check the build log by clicking the deployment row in the Deployments tab
2. Look for a hanging process (e.g., a script waiting for interactive input)
3. If there is no log output at all, try triggering a fresh deploy

---

Getting help

If the above doesn’t resolve your issue, email support@zanode.co.za with:

• Your project name
• When the issue started
• Any error messages from Logs or Deployments