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