Replit Agent deployment failed? Common causes and fixes
Why a Replit app works in Preview but fails to publish, how to read the publishing logs, and the fixes for ports, secrets, start commands and health checks.
Leer en español →
When an app built with Replit Agent runs in Preview but fails to publish, the cause is almost always one of five things: the server listens on localhost instead of 0.0.0.0, the port configuration doesn't match, production Secrets were never added, the start command exits instead of running a server, or the homepage is too slow to pass Replit's health check. The Logs tab in the Publishing pane tells you which one it is.
This guide walks through each cause in the order worth checking, shows what the fix looks like, and covers the second kind of failure: publishing succeeds but the live URL is broken.
Does the app actually work in Preview?
Start here, because publishing can't fix an app that is already broken. Run the app from the Project Editor and make sure the Preview (the replit.dev address) loads and the main flow works: sign up, log in, create something, see it saved.
If Preview fails too, the problem isn't deployment. Fix the error in the workspace first, and only then publish again.
Where do I find the real error?
Open the Publishing pane and go to its Logs tab. Read from the top of the failed attempt, not the bottom. Look for:
- A stack trace with a file name and line number.
Cannot find moduleor a missing package.- A command that failed during the build step.
- A variable that is
undefinedat startup.
Copy the first real error line. If you ask Agent for help, paste that line instead of "deployment failed". Agent fixes a specific error much more reliably than a vague one.
Why does it fail even though Preview works?
1. The server listens on the wrong address
Replit's docs are explicit: a published app must listen on 0.0.0.0. A server bound to localhost or 127.0.0.1 can look fine in the workspace and still fail once published.
In an Express app, the fix is one line:
const port = process.env.PORT || 3000;
app.listen(port, "0.0.0.0");In Python with Flask or FastAPI, pass host="0.0.0.0" (or --host 0.0.0.0 to Uvicorn).
2. The port configuration doesn't match
Replit usually detects your port automatically. The catch: if your .replit file has a [[ports]] section, automatic detection is turned off. Then the entry for your app must map externalPort = 80 to the localPort your server really uses. A common Agent mistake is leaving an old port entry behind after switching frameworks, so the platform probes a port nothing is listening on.
Open .replit, check every [[ports]] block, and either remove the stale ones or make the localPort match the server.
3. Production Secrets are missing
This one catches almost everyone. Secrets set in the Project Editor do not carry over to the published app automatically. You add them separately in the Publishing pane.
Symptoms of a missing Secret include errors about undefined values at startup, failed calls to an API such as OpenAI or Stripe, a database connection that refuses to open, and login or payment flows that break only on the live site. Go through every Secret in the workspace and confirm the published app has its own value. Use live keys only where you mean to.
4. The start command exits
Published apps are expected to keep running. If your run command executes a script that finishes (a seed script, a build that never starts a server, a one-off migration), Replit restarts it, and it never becomes healthy.
Check the build and run commands in the Publishing pane. A typical Node setup builds first (npm run build) and then starts a long-running process (npm run start). Typos, wrong entry files and commands that only worked on someone's laptop are all common here.
5. The homepage is too slow for the health check
Before marking an app live, Replit sends a request to it. According to its troubleshooting docs, if the homepage takes more than five seconds to respond, publishing can fail at the last step.
Apps built by Agent often do heavy work on the first request: loading a large dataset, calling an AI model, or running migrations at startup. Move that work behind a user action, cache it, or run it after the server is listening.
Is the deployment type wrong for the app?
A Static deployment serves only HTML, CSS and JavaScript files. If your app has API routes, auth callbacks, server-side database calls or any backend logic, it needs Autoscale or Reserved VM instead. You can change this in the Publishing pane. Our guide on why Replit apps go to sleep explains the differences between the deployment types.
Size is the other limit: Replit's docs list 8 GB for Autoscale and Reserved VM deployments and 1 GB for Static ones. Large files committed by accident (videos, datasets, node_modules copies) can push you over.
Publishing worked but the live site is broken. Now what?
Compare the live app against Preview on these points, which are the usual suspects:
| Check | What usually goes wrong |
|---|---|
| Secrets and environment variables | Present in the workspace, missing in Publishing |
| Database | App still pointing at the development database |
| Login redirect URLs | Auth provider only allows the replit.dev address |
| Payment webhooks | Stripe sends events to the old URL or uses test keys |
| CORS and API allowlists | The new domain isn't on the list |
| Files written to disk | Lost on every publish |
The last row deserves a note. Replit's docs state that the file system of a published app is not persistent and resets every time you publish. If users upload avatars and they vanish after an update, that is why. Store files in a database or a storage service instead. Our guide to Replit databases in production covers where data should live.
How do I stop this from happening again?
- Keep a short checklist of every Secret the app needs, and update it whenever Agent adds an integration.
- Read the diff before you accept large Agent changes to
.replit,package.jsonor the server entry file. - After each publish, test the live URL in a private window: sign up, log in, do the main action.
- Watch the logs for a day after big changes. Our guide to monitoring and error tracking shows how to get alerts instead of finding out from users.
For broader preparation, see moving a vibe-coded app from preview to production.
Quick answers
Why does my Replit app work in Preview but not when published? Usually because production Secrets weren't added in the Publishing pane, the server listens on localhost instead of 0.0.0.0, or the port in .replit doesn't match the server.
Where are Replit deployment logs? In the Publishing pane, under the Logs tab. Read the first error of the failed attempt.
Can Replit Agent fix a failed deployment by itself? Often, if you give it the exact error line from the logs. It can't add production Secrets for you or know which live keys you intend to use.
Why do uploaded files disappear after I publish? The published file system resets on every publish. Save files to a database or storage service.
Still stuck?
If the logs don't point anywhere obvious, run the free health check on your live URL to see what is visible from outside. When you'd rather hand it over, our Replit app rescue starts with a review of the code and the publishing setup, and fixes come with a fixed price you approve first. You can also describe the problem and a person will reply within one business day.
