Fix Scalingo 502 Bad Gateway & Container Crash Loops

Resolve 502 Bad Gateway errors and crash loops in Scalingo by correctly configuring PORT binding and Procfile start commands.

The Problem: Successful Deployment, Failed Runtime

A common point of confusion in Scalingo is the "successful deployment" notification followed by a 502 Bad Gateway error or a container that continuously restarts. This happens because the build process (compiling code, installing dependencies) succeeded, but the application process failed to bind to the network interface required by the Scalingo router.

The primary takeaway: Your application must bind to 0.0.0.0 using the dynamic port provided by the PORT environment variable. Hardcoding ports or binding to localhost will result in a routing failure, even if the application is running internally.

Quick Diagnostic Matrix

Symptom	Likely Cause	Primary Check
502 Bad Gateway (Immediate)	Port Mismatch	Check for hardcoded ports (e.g., 3000, 8000)
Container Crash Loop	Procfile Error	Verify start command in `Procfile`
502 Bad Gateway (Intermittent)	Binding to 127.0.0.1	Verify binding address is `0.0.0.0`
Crash after few seconds	Missing Env Var	Check runtime logs for "Missing Variable" errors

Step-by-Step Verification Process

1. Analyze the Process State

First, determine if the container is actually running or if it is crashing and restarting. Use the Scalingo CLI to check the status of your web process.

# Run from your local terminal with app permissions
scalingo app:processes [APP_NAME]

If the status shows starting or restarting repeatedly, the issue is a crash loop. If it shows running but you see a 502, the issue is likely the network binding.

2. Inspect the Runtime Logs

Stream the logs to find the exact error occurring during the boot sequence. Look for EADDRINUSE or Connection refused errors.

# Stream logs for the web process
scalingo app:logs [APP_NAME] -t web

Warning: If the logs are empty or stop abruptly, the container may be crashing before the logging agent can capture the output. Check the build logs to ensure the buildpack selected the correct runtime.

3. Validate the PORT Binding

Scalingo injects a PORT environment variable into every container. Your application must use this variable. If you hardcode a port, the Scalingo router cannot find your application.

Incorrect (Hardcoded): app.listen(3000)

Correct (Dynamic): const port = process.env.PORT || 3000; app.listen(port, '0.0.0.0');

Note that binding to localhost or 127.0.0.1 will fail because the router communicates with the container via the container's internal IP, not the loopback interface.

4. Audit the Procfile

The Procfile tells Scalingo exactly how to start your app. If missing, Scalingo attempts to guess the start command based on the buildpack, which often fails for custom frameworks.

Ensure your Procfile (located in the root directory) defines the web process type:

web: npm start

Or for Python/Gunicorn:

web: gunicorn myapp:app

Fixes and Implementation

Fixing Port Binding

Update your application entry point to prioritize the environment variable. For a Node.js application, the implementation should look like this:

// server.js
const port = process.env.PORT || 3000;
server.listen(port, '0.0.0.0', () => {
  console.log(`Server running on port ${port}`);
});

Fixing the Start Command

If the logs indicate a "Command not found" or "Module not found" error, explicitly define the start command in your Procfile. Avoid using shell scripts (e.g., web: ./start.sh) unless the script is marked as executable in git: git update-index --chmod=+x start.sh.

Verification and Rollback

To verify the fix, commit the changes and push to Scalingo:

git add .
git commit -m "Fix: bind to PORT env var and update Procfile"
git push scalingo master

Check the dashboard to ensure the web process remains in the running state for more than 5 minutes and that the app URL returns a 200 OK response.

Rollback: If the new configuration causes a different failure, revert the commit and push again:

git revert HEAD
git push scalingo master

Escalation Criteria

If you have verified the following and the 502 persists, contact Scalingo support:

The process status is running.
The app is binding to 0.0.0.0 and the PORT environment variable.
Local testing with PORT=[random_port] works.
The logs show the application has started successfully and is listening for requests.

To add to the diagnostic matrix, it is important to distinguish between a process that is running and one that is ready. Even if scalingo app:processes shows the web process as running, the router may still return a 502 Bad Gateway if the application fails its readiness probe.

Scalingo's router typically performs a basic HTTP GET request to verify the application is capable of handling traffic. If your application takes a long time to boot (e.g., due to heavy database migrations or large asset compilation at startup) or if the root endpoint returns a non-200 status code, the router will mark the instance as unhealthy.

Practical Verification

Implement a Health Endpoint: Create a lightweight /health or /ping route that returns a 200 OK without performing heavy database queries.
Check Boot Time: If your app crashes only during the first 30–60 seconds after a push, check if the startup sequence is exceeding the router's timeout window.

Diagnosing 502 Bad Gateway and Crash Loops in Scalingo Deployments