502 Bad Gateway after deploy: bind to 0.0.0.0 and $PORT

Because the proxy in front of your app can't connect to it. On your laptop you open localhost:5000 from the same machine, so an app listening on 127.0.0.1 works fine. On a hosting platform, requests arrive from a proxy in another container or machine. An app bound to 127.0.0.1 only accepts connections from itself, so the proxy gets nothing back and returns 502.

The second cause is the port. Platforms tell your app which port to use through the PORT environment variable. An app that always listens on 5000 or 8000 is running, just not where the proxy is looking.

Every major platform documents the same rule:

• Render: “Every Render web service must bind to a port on host 0.0.0.0 to serve HTTP requests.” Its default PORT is 10000.
• Railway says the most common reason for “Application failed to respond” is that the app “is not listening on the correct host or port.”
• Heroku assigns the port as PORT and kills a web process that hasn't bound to it within 60 seconds (error R10, which then shows up as H10 App crashed).

Most development servers default to 127.0.0.1 on purpose, so your work-in-progress isn't reachable from the network. That default is what breaks in production.

Read the port from the environment and listen on all interfaces. The start commands:

# Node / Express
app.listen(process.env.PORT || 3000, "0.0.0.0")

# FastAPI, Starlette (uvicorn)
uvicorn main:app --host 0.0.0.0 --port $PORT

# Flask, Django (gunicorn binds 0.0.0.0:$PORT on its own when PORT is set)
gunicorn app:app
gunicorn myproject.wsgi

# Vite static preview
vite preview --host 0.0.0.0 --port $PORT --strictPort

# Go
http.ListenAndServe(":"+os.Getenv("PORT"), nil)

Three gotchas that look like a 502 but aren't a missing host:

• Next.js can't take PORT from a .env file. Its docs say the HTTP server boots before .env is read. Set PORT in the platform's environment instead.
• Vite moves to the next free port when the one you asked for is busy. Add --strictPort so it fails loudly instead of listening somewhere else.
• Django's runserver and Flask's flask run are development servers. Their docs say not to use them in production. Run gunicorn instead.

EthioDeploy sets PORT=3000 and HOSTNAME=0.0.0.0 for every web service, and overrides any value you set for those two. Then every deploy waits for a health check: a GET to / that has to return a 2xx or 3xx status within 30 seconds.

If the app never answers, the deploy fails and your previous version keeps serving traffic, so a wrong bind never takes the site down. The build log says what went wrong:

Health check timed out after 30000ms. The app never answered on port $PORT.
Make sure it listens on 0.0.0.0 and reads the PORT env var.

If your home page needs a login or returns 404 by design, set a Health Check Path such as /healthz in Settings. The framework guides list the exact start command for each stack: Express, FastAPI, Django, Flask and Go.