Documentation

Troubleshooting Guide

Common issues and solutions for SnapDeploy deployments.

Build Issues

Build fails with "npm ERR! code ENOENT"

Cause: package.json not found in root directory.

Solution:

Ensure package.json is in the root of your repository
If using a monorepo, set the Root Directory in container settings
Check that the branch you're deploying has package.json

Build fails with memory error

Cause: Build process exceeds memory limits.

Solution:

Choose a larger container size (Always-On Medium 2 GB / Large 4 GB)
Optimize your build process (e.g., fewer dependencies)
Use a pre-built Docker image instead

Build times out

Cause: Build exceeds the 60-minute limit (most builds finish in 1–5 minutes).

Solution:

Use smaller base images (e.g., Alpine variants)
Optimize Dockerfile layers for caching
Remove unnecessary dependencies
Consider multi-stage builds

Container Startup Issues

Container keeps restarting

Cause: Application crashes on startup.

Debugging Steps:

Check container logs in the dashboard
Verify all required environment variables are set
A variable you set in Container Settings overrides the same name in your Dockerfile; remove it there if you want the image's value
Ensure your app listens on the configured port
Check for missing dependencies

Health check fails

Cause: Application not responding on configured port.

Solution:

Verify your app listens on 0.0.0.0, not 127.0.0.1
Check that the port matches your container settings
Add a /health endpoint that returns 200 OK
Ensure app starts within 5 minutes

"EADDRINUSE" or "port already in use"

Cause: Port configuration mismatch.

Solution:

Ensure your app reads PORT from environment variables
Use process.env.PORT || 3000 in Node.js
Update container settings to match your app's actual port

Network Issues

502 Bad Gateway error

Cause: Container not responding or not healthy.

Solution:

Check container status in dashboard
Review container logs for errors
Restart the container
Verify health check endpoint is working

Cannot connect to external database

Cause: Either the database does not allow connections from SnapDeploy, or it listens on a port outside the range containers can reach. Containers can open outbound connections on TCP ports 1 to 27017 (3333 and 9000 to 9099 excluded) on every plan; a connect ETIMEDOUT against a database on a higher port, for example an Aiven service on port 27814, is this rule and not the database.

Solution:

If the database port is above 27017, move to a provider on a standard port (MySQL 3306, PostgreSQL 5432, TiDB 4000, MongoDB 27017) or use a SnapDeploy add-on, which is reached over the internal network
Allow connections from 0.0.0.0/0 or SnapDeploy IP ranges
Verify database credentials in environment variables
Check that database URL includes correct port
Ensure SSL is configured correctly if required