Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

Heroku kills a Node.js app that does not bind to $PORT in time

ErrorError R10 (Boot timeout) -> Web process failed to bind to $PORT within 60 seconds of launch

Short answer

Heroku gives a web process 60 seconds to listen on the port it assigns in $PORT, then kills it with R10. For Node.js the usual causes are a hard-coded port, a Procfile without a web process, or slow work before app.listen runs. Read the log, listen on process.env.PORT, and open the port first.

  • Applies to Heroku Cedar, Node.js 22, Express 5
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Stream the app log, restart the dyno and watch for the Starting process line. It shows the command Heroku ran, and whether your own startup message appears before the R10 line.

    heroku logs --tail --app my-app
  2. 2Match what you see, then jump to its fix

    1. 1Your log says Listening on 3000 (or another fixed number) and then R10 followsThe server listens on a fixed port instead of $PORTFix
    2. 2The Starting process with command line shows a command that is not your server, or the app has no web dynoThe Procfile has no web process, or runs the wrong fileFix
    3. 3The log shows the app starting normally, nothing from listen(), then R10 after 60 secondsSlow startup work runs before the server listensFix

What does the error look like?

  • Error R10 (Boot timeout) -> Web process failed to bind to $PORT within 60 seconds of launch
  • Stopping process with SIGKILL
  • State changed from starting to crashed

Cause 1 of 3

The server listens on a fixed port instead of $PORT

1Check

Heroku assigns the port at runtime and puts it in the PORT environment variable. Search the code for a literal port in listen().

grep -rn "listen(" --include=*.js --include=*.mjs --include=*.ts --exclude-dir=node_modules .

2Fix

Read the port from the environment and keep a number only as a local fallback.

const port = process.env.PORT || 5006;
app.listen(port, () => {
  console.log(`Listening on ${port}`);
});

3Verify

Deploy and check that the log prints the assigned port and no R10 follows.

heroku logs --tail --app my-app

Confirmed by devcenter.heroku.com

Did this fix it?

Cause 2 of 3

The Procfile has no web process, or runs the wrong file

1Check

Only the process type called web receives HTTP traffic from Heroku. Compare the Procfile with the file that calls listen().

cat Procfile

2Fix

Declare a web process that starts the file with your server, commit the Procfile and deploy again.

# Procfile
web: node index.js

3Verify

After the deploy the log should show your Listening line and no R10.

heroku logs --tail --app my-app

Confirmed by devcenter.heroku.com

Did this fix it?

Cause 3 of 3

Slow startup work runs before the server listens

1Check

Look for await calls before app.listen, such as a database connect, migrations or loading large data. Heroku names an external resource that is slow or unreachable, and too much startup work, as typical reasons.

grep -rn "await" index.js

2Fix

Start listening first, then connect to the database and other services without blocking startup. Reduce the code and dependencies loaded at boot.

app.listen(port, () => console.log(`Listening on ${port}`));
connectDatabase().catch((err) => console.error('DB connect failed', err));

3Verify

Deploy and compare the time between the Starting process line and the first request being served.

heroku logs --tail --app my-app

Confirmed by devcenter.heroku.com

Did this fix it?

How do I stop it coming back?

  • Keep the pattern process.env.PORT || localPort in one place and reuse it.
  • Keep slow work out of the web process boot; open the port first.
  • Check heroku logs after every first deploy of a new process type.
  • Treat the boot timeout tool as temporary: it hides slow boots and makes deploys harder, as Heroku states.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.