QAlaunch

Replit deployment failed health check: how to get it to publish

Before Replit puts a deployment live it sends a request to your homepage, and if the server does not answer in time on the expected address and port, publishing fails. The common causes are a server listening on localhost or 127.0.0.1 instead of 0.0.0.0, a [[ports]] block in .replit whose externalPort is not 80, a homepage that takes more than about five seconds to respond, or a process that exits instead of staying up. Fix the binding and port, make the homepage fast, and publish again.

Opens your site in a real browser on desktop and phone. Free, about two minutes, no signup. Full report from $19.

What you'll see

The publish runs through build and bundling, then fails on the final promotion step. Or it appears to succeed, but the replit.app URL shows "The deployment could not be reached" or hangs until it times out.

Why it happens

1. The server only listens on localhost

A server bound to 127.0.0.1 accepts connections from inside its own container only. That works for the workspace preview, but Replit’s health check and your visitors arrive from outside, so they get no answer.

2. The .replit ports block is wrong

If .replit defines [[ports]], automatic port detection is turned off. The entry for your web server must map its localPort to externalPort 80, or the promotion step cannot find the app.

3. The homepage is too slow on startup

Replit’s docs say the health check can time out if the homepage takes longer than five seconds. Seeding a database, building a cache or calling a slow API before the server starts listening is enough to cause that.

4. The process does not keep running

A script that does its work and exits is not a web server. Replit restarts it, but there is never a server waiting for the health check request.

How to fix it

  1. Open Publishing > History, choose the failed attempt and read its logs. The first ERROR or FAILED line usually names the problem.
  2. Find where the server starts listening and change the host to 0.0.0.0 and the port to process.env.PORT, with a fallback for development. In Express that is app.listen(port, "0.0.0.0").
  3. Open .replit. If there is a [[ports]] section, make sure the web server’s localPort matches the port the app listens on and externalPort is 80, or remove the block so Replit detects the port itself.
  4. Move slow work out of startup. Start the server first, then run migrations, cache warm-ups or data imports in the background, or trigger them on first use.
  5. Confirm the run command in the Publishing pane starts the long-running server, not a one-off build or seed script.
  6. Publish again and watch the logs until the deployment is promoted, then open the URL in a private window.

Prompt to paste into Replit

Publishing on Replit fails the health check. Make the server listen on 0.0.0.0 using the PORT environment variable, make GET / respond in under a second by moving slow startup work to after the server is listening, check the [[ports]] config in .replit so the web port maps to externalPort 80, and confirm the run command starts a process that keeps running.

How to check it's fixed

  • The publish completes and the deployment shows as live in the Publishing pane.
  • The replit.app URL starts showing content within a few seconds in a private window, including on the first load after a republish.

What a QAlaunch scan shows for this

  • The site failing to load or returning an error page on the scanned URL.
  • Slow server response time on the homepage from the PageSpeed audit.
  • Console errors and failed requests once the page does load, which point to startup problems the health check did not catch.

See exactly what a full report contains in the sample report.

Frequently asked questions

Why does the preview work if the binding is wrong?

The workspace preview is more forgiving about how the server is reached. A published deployment is reached from outside the container, which only works when the server listens on 0.0.0.0.

Can I make the health check wait longer?

Replit’s docs describe the timeout but no setting to extend it. The reliable fix is to make the homepage answer quickly and do heavy work after the server is up.

My app is a static front end. Why is it failing?

Check the deployment type. A front-end-only build fits a Static deployment, which serves files without a server; an Autoscale deployment expects a process that listens on a port.

Done for you · not automated

Rather have a QA engineer test it by hand?

If this is a site you're launching or handing to a client, I'll go through it by hand, including the Replit-specific issues a scan can't reach, like logged-in flows.

$299one-time · 3 business days
  • Up to 10 key pages tested by hand, not a scan
  • Every flow a customer uses: forms, sign-up, checkout, booking
  • Real mobile and desktop browsers
  • A written report in plain language, with screenshots
  • A 15-minute call to walk you through it
  • 10 years of professional QA experience

Tell me about your site and I'll reply personally, usually the same day.

No payment now. I'll confirm scope and price first.

Related fixes

More for Replit: all Replit fixes · Replit testing

Written by Waqas Ahmad, QA engineer with 10 years of professional testing experience. Last checked October 26, 2026.

Sources: Replit docs: publishing troubleshooting · Replit forum: the deployment could not be reached · Replit forum: publishing does not work