Troubleshooting Overview

When something goes wrong, start by identifying what type of issue you're facing. This guide helps you find the right place to look.

Decision Tree

"My build failed"

→ Check deployment build logs in the dashboard (Application → Deployments → click on the failed deployment)

Common causes:

• Missing requirements.txt, package.json, or Gemfile
• Dependency installation errors (version conflicts, missing system libraries)
• Build command errors
• Dockerfile syntax errors

See Build Failures for detailed solutions.

"My deployment failed or timed out"

→ Check deployment logs and application logs

Common causes:

• The release command failed (e.g., migration error)
• The web process crashes on startup
• The app doesn't bind to the correct port
• The container runs out of memory

See Deployment Failures for detailed solutions.

"My app shows a 502 error"

→ Check application logs (Application → App Logs)

Common causes:

• The web process crashed or isn't running
• The app isn't listening on the expected port
• The container port doesn't match the configured port
• The app takes too long to start

See App Not Responding for detailed solutions.

"My custom domain doesn't work / no SSL"

→ Check DNS configuration and domain status in the dashboard

Common causes:

• DNS records not propagated yet (can take up to 24 hours)
• Wrong A record IP address
• Domain added before DNS propagation completed (delete and re-add)
• Custom domains require a paid plan

See Domain & SSL Issues for detailed solutions.

"My database won't connect"

→ Check environment variables and database status

Common causes:

• Database container is stopped
• Using the wrong connection URL variable
• Application code not reading the environment variable
• Firewall blocking connections

See Database Connection Issues for detailed solutions.

"Server setup failed"

→ Check server setup logs on the server detail page

Common causes:

• Server doesn't meet OS requirements (need Ubuntu 22.04/24.04 or Debian 12)
• SSH connection issues (wrong credentials, firewall)
• Server already has Docker or Nginx installed (use a fresh server)

See Server Setup Failures for detailed solutions.

"Server RAM or disk alerts"

→ Check server monitoring on the server overview page

tip

RAM spikes during deployment builds are normal, especially for JavaScript/TypeScript projects. These are temporary and resolve after the build completes. Consider a larger server if builds consistently fail due to memory.

Where to Find Logs

Log type	Where to find it
Build logs	Application → Deployments → click deployment
Application logs	Application → App Logs
Cron job logs	SSH to server: ssh app@<server-ip>, then cd /home/app/_cron_logs
Server setup logs	Servers → click server → Setup Logs
Database logs	Application → Databases → Manage → click database