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:

  • Upgrade to a plan with more memory
  • Optimize your build process (e.g., fewer dependencies)
  • Use a pre-built Docker image instead

Build times out

Cause: Build exceeds 15-minute limit.

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:

  1. Check container logs in the dashboard
  2. Verify all required environment variables are set
  3. Ensure your app listens on the configured port
  4. 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: Database not allowing connections from SnapDeploy.

Solution:

  • 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

Custom domain not working

Cause: DNS not configured correctly.

Solution:

  • Add CNAME record pointing to your-container.containers.snapdeploy.dev
  • Wait 5-30 minutes for DNS propagation
  • Verify domain is added in container settings
  • Use dig your-domain.com to check DNS

Performance Issues

Application is slow

Solutions:

  • Check CPU and memory metrics in dashboard
  • Upgrade to a plan with more resources
  • Optimize your application code
  • Enable auto-scaling (Pro plan+)
  • Consider caching (Redis)

Container running out of memory

Solutions:

  • Upgrade to a plan with more RAM
  • Optimize memory usage in your application
  • Check for memory leaks
  • Use streaming for large file operations

Need More Help?

If you can't find a solution, our support team is here to help:

Contact Support View FAQ

When contacting support, include: container ID, deployment ID, and relevant log excerpts.

Supported Technologies FAQ