Introducing Livops 2.0! Promo codeCEOgives you 8,000 so‘m on your balance.What’s new

App not listening on $PORT: why the health check failed after deploy

The platform started your app, tried the port it gave it, and nothing answered in time. Almost always the app listens on its own fixed port instead of the PORT variable, listens on localhost (127.0.0.1) instead of 0.0.0.0, or crashed or was still starting when the check gave up. Listen on 0.0.0.0 and the port in PORT, and it passes.

By Livops team, the people who build and run LivopsUpdated

The message differs from platform to platform. On Livops the deploy ends with:

the application did not answer within 1m0s. Its last output:

followed by the app’s last lines. Elsewhere it reads as “health check failed”, “no open ports detected” or “application failed to respond”. This page explains what the check does, lists the causes from the most common, shows how to run the same check on your machine, and says what Livops does when an app does not answer.

What does the error mean?

A platform that runs web apps gives each one a port, usually in the PORT environment variable, starts it, and then connects to that port from outside the app’s container. When something answers there, traffic is switched to the new version. When nothing answers before the deadline, the deploy fails, even if the app is running and printing “Server started”.

So the app was either not listening at that address, or not listening yet.

Causes, most common first

1. The app listens on its own port, not on PORT

app.listen(3000), app.run(port=5000), or a server whose default is 8000, such as Uvicorn[2]. Read the port from the environment:

// Node / Express
app.listen(Number(process.env.PORT) || 3000, '0.0.0.0')
# Python
uvicorn main:app --host 0.0.0.0 --port $PORT
gunicorn app:app            # binds 0.0.0.0:$PORT when PORT is set

Gunicorn binds 0.0.0.0:$PORT by default when PORT is set, and 127.0.0.1:8000 when it is not[3]. next start reads PORT too, with 3000 as its default[4].

2. The app listens on localhost

127.0.0.1 accepts connections only from inside the container; the platform’s check comes from outside. Uvicorn listens on 127.0.0.1 unless you pass --host 0.0.0.0[2], and so does Gunicorn without PORT or --bind[3]. In Node, a server with no host given accepts connections on every address[1], so the problem is passing 'localhost' or '127.0.0.1' yourself. Next.js’s own default host is 0.0.0.0[4].

flask run --host 0.0.0.0 --port $PORT
python manage.py runserver 0.0.0.0:$PORT   # development server only

3. The app crashed, or exited, before the check

Not a port problem at all: a missing variable, a missing module, a database it could not reach. The app’s last lines say which. Fix that, and the port check passes.

4. The app is still starting when the check gives up

Migrations, a model download or a cache warm-up run before the server starts listening. Start listening first and do slow work afterwards, or move migrations into a step that runs before the start.

5. The health check path does not answer with success

If a health path is configured, it has to return a success status: a route that redirects to a login page, returns 404, or waits on a slow database fails the check. Add a plain route for it:

app.get('/healthz', (req, res) => res.send('ok'))

6. It is not a web app

A Telegram bot that polls, a queue worker, a cron script: none of them opens a port. Deploy it as a bot or a worker, not as a web service.

How to confirm the fix locally

Start the app the way the platform does — with a PORT you choose — and check from outside its process:

PORT=4321 npm start &
curl -i http://127.0.0.1:4321/
lsof -nP -iTCP:4321 -sTCP:LISTEN     # macOS and Linux
ss -ltnp | grep 4321                 # Linux

The listening address should be *:4321, 0.0.0.0:4321 or [::]:4321, not 127.0.0.1:4321. The test that matches a platform best is a container, because there localhost inside is not reachable from outside:

docker run --rm -e PORT=8080 -p 8080:8080 myapp
curl -i http://localhost:8080/

If curl gets an answer, the platform will too.

On Livops

  • PORT and HOSTNAME are set. Every web service gets PORT (3000 by default; for a Docker image, the port you specified, which must be 1024 or higher) and HOSTNAME=0.0.0.0.
  • One minute to answer. Livops waits up to a minute for the app to answer on that port. Without a health path any HTTP answer counts; with healthPath in livops.json, that path has to answer with a 2xx or 3xx.
  • An app that ignored PORT is moved once. If the app did not answer on PORT but listens on exactly one other port, 1024 or higher, Livops starts it once more on that port, keeps the port for the project’s next deploys, and the log says: the application listens on that port and ignored PORT, so it is reached there; listening on PORT is recommended. If it listens on several ports, Livops does not guess which one serves the site; the log lists them, and the assistant points you to the settings.
  • Tips for the other causes. When the app’s output says it listens on localhost, the log adds a Tip: to listen on 0.0.0.0. A missing variable or Python module gets its own Tip. An app that printed nothing and never answered gets a note that a bot or a worker opens no port, and should be made as a Bot.
  • The previous version keeps serving. A failed start is start_failed; nothing is switched, and the version that worked keeps answering.
  • The assistant explains. The button next to a failed deploy reads this log and says what to change. Anything it proposes, such as a new start command, is a card that does nothing until you press it.

The same cases in the docs: The app listens on localhost, and healthPath and memory in Frameworks and livops.json.

Questions

What is the difference between 127.0.0.1 and 0.0.0.0?

127.0.0.1 accepts connections only from inside the same machine or container. 0.0.0.0 accepts them on every network interface, which is what lets the platform's proxy reach the app from outside its container.

Why does it work locally?

Locally your browser runs on the same machine, so localhost reaches the app, and you open whatever port it chose. On a platform the check comes from outside the container, to the port in PORT.

Do I need a health check endpoint?

Not always. Many platforms accept any answer on the port. If you configure a health path, it must answer with a success status without a login, quickly, and without depending on slow services.

My app is a Telegram bot or a background worker. Why does it need a port?

It does not. It was deployed as a web service, which is expected to answer HTTP. Deploy it as a bot or worker, which has no port and no health check.

Does Livops pick up the port my app chose?

Once. If the app ignored PORT and listens on exactly one other port, 1024 or higher, Livops starts it again on that port, keeps it for the next deploys, and says so in the log. Listening on PORT is still the recommended fix.

Sources

  1. Node.js docs — net, server.listen() (nodejs.org). Checked .
  2. Uvicorn — Settings (uvicorn.dev). Checked .
  3. Gunicorn — Settings (bind) (gunicorn.org). Checked .
  4. Next.js docs — next CLI (nextjs.org). Checked .

Put your project online today

Connect GitHub or drop a folder. No card is asked for.

Deploy your app

Got a question? — @livops_uz