Replit deployment failed / published app not working: a fix guide
Your app runs fine in the Replit workspace. You click Deploy (Autoscale, Reserved VM or Static), and either the deployment fails with a red log, or it succeeds and the published URL is blank, spins forever, or returns an error. This guide walks through the failures we see most often on Replit Deployments for vibe-coded apps (often Next.js, Express, or Vite apps started with AI).
If the code also lives on GitHub and the failure looks like a generic Vite/Next build problem, also see Module not found and missing environment variables.
Step 0: read the two different logs
Replit Deployments have a build phase and a runtime phase. They fail for different reasons.
- Build log red: install failed, TypeScript/Vite/Next build failed, or the build command is wrong. Fixes 1–3.
- Build green, runtime red or blank site: wrong run command, wrong port, missing secrets, health check failing, or SPA routing. Fixes 4–8.
Copy the first real error line (skip warnings). Paste that into any AI chat instead of "my deploy failed".
1. Wrong build or run command
Signature: Deployment config points at npm start but the project has no start script, or it runs node index.js when the entry is server.ts.
Open the Deployment configuration and set commands that match package.json:
// typical Vite + preview (static-ish)
"scripts": {
"build": "vite build",
"start": "vite preview --host 0.0.0.0 --port ${PORT:-5000}"
}
// typical Next.js
"scripts": {
"build": "next build",
"start": "next start -H 0.0.0.0 -p ${PORT:-3000}"
}
// typical Express
"scripts": {
"build": "tsc",
"start": "node dist/index.js"
}
For Static Deployments, the build output directory must match what you configured (often dist or build). If the folder is empty after build, the publish step uploads nothing useful.
2. Dependencies missing in production
Signature: runtime says Cannot find module 'express' or a package that worked in the workspace.
AI scaffolds sometimes put runtime packages in devDependencies. Replit production installs may omit them. Move anything the server needs at runtime into dependencies, delete node_modules, run a clean install, and redeploy.
npm install express # ensures it lands in dependencies npm ls express
3. Build tools and Nix packages
Signature: native modules fail to compile (node-gyp, sharp, canvas), or a system binary is missing.
Replit uses Nix for system packages. If your app needs python3, pkg-config or similar at build time, add them via the Replit Packages / Nix UI so the Deployment image includes them. Pin versions when the AI "fixed" a build by upgrading a native addon that needs build tools.
4. The process binds to localhost only
Signature: Deployment shows "running" but the public URL times out or shows a gateway error.
Inside the workspace, binding to 127.0.0.1 is fine. On a Deployment, the proxy cannot reach a process that only listens on localhost. Bind to all interfaces and use Replit's port:
// Express
const port = Number(process.env.PORT) || 5000;
app.listen(port, "0.0.0.0", () => console.log(`listening on ${port}`));
// Next.js (package.json)
"start": "next start -H 0.0.0.0 -p ${PORT:-3000}"
Hard-coded 3000 without reading process.env.PORT is a common AI mistake on Replit.
5. Secrets not available to the Deployment
Signature: blank page with supabaseUrl is required, API 401s, or process.env.FOO is undefined only in Production.
Workspace Secrets do not always flow to Deployments until you mark them for Production / enable them in the Deployment settings. After changing secrets, redeploy. For Vite frontends, remember that only VITE_ names are exposed to the browser, and they are inlined at build time — so a secret added after the build still requires a new build.
6. Health checks and the home route
Signature: Deployment keeps restarting; logs show health check failed.
Autoscale Deployments probe a path (often /). If your app redirects / to /login with a 500, or the server is not ready yet, the probe fails and Replit kills the machine. Temporary mitigations:
- Serve a cheap
GET /healththat returns 200 immediately, and point the health check there if the UI allows it. - Make sure the server listens before doing heavy startup work.
- Do not block the event loop on a cold Supabase call during boot.
7. SPA routing on Static Deployments
Signature: Static Deployment serves the home page, but /dashboard 404s on refresh.
Same SPA rule as Netlify: every client route must fall back to index.html. Configure the Static Deployment's rewrite/fallback to index.html, or switch to an Autoscale Deployment that runs a Node server which already handles routing (Next.js).
8. Database and auth URLs still point at development
Signature: published app talks to a local Postgres, a Neon branch that slept, or Supabase redirects to a Replit preview URL.
Search the repo for hard-coded hosts:
grep -rn "localhost\|127.0.0.1\|replit.dev\|DATABASE_URL" . --include='*.ts' --include='*.js' --include='*.env*'
Put production URLs in Secrets. For Supabase, add the Deployment's public URL to Redirect URLs. For Postgres, confirm the production database allows connections from Replit's egress (some providers require allowing all IPs or using a pooled URL).
Replit + GitHub: a saner workflow
Many vibe coders develop on Replit and also push to GitHub. That is good: you get a real history, and tools like VibeRescue can open a pull request against the repo. Before you Deploy:
- Push a clean commit that builds with
npm ci && npm run buildoutside Replit (GitHub Actions or your laptop). - Keep Secrets out of the repo (no
.envcommits). - Use the same Node major version everywhere.
If GitHub builds green and Replit Deployments fail, the difference is almost always the run command, port binding or Secrets — not "Replit is broken".
A Deployment checklist
- Build command and run command match
package.json. - Runtime dependencies are in
dependencies, not onlydevDependencies. - Server listens on
0.0.0.0andprocess.env.PORT. - Production Secrets are set; Vite apps redeployed after changes.
- Health check path returns 200 quickly.
- Static apps have an
index.htmlfallback for client routes. - No localhost database or auth URLs in production.
- Incognito test of signup, login and a write path on the public URL.
When to stop prompting and fix the host settings
If the AI keeps editing React components while the log says Error: listen EADDRINUSE or PORT is undefined, you are in the wrong layer. Host and process settings cannot be fixed by rewriting UI. Change the Deployment config, redeploy, and only then ask for code changes if the new log still shows an application error.
FAQ
Why did my Replit Deployment fail?
Common causes are a wrong run command, a missing build step, secrets not marked for Deployment, the app listening on the wrong port, or a health-check URL that returns non-200. Open the Deployment build and runtime logs and fix the first red error.
Why does my Replit app work in the workspace but not when published?
The workspace injects Secrets and runs your process interactively. Deployments need an explicit build/run command, Secrets enabled for Production, and the HTTP server bound to 0.0.0.0 on the port Replit expects (usually process.env.PORT).
How do I set environment variables for a Replit Deployment?
Use the Secrets tool in the Replit workspace, then ensure those secrets are available to the Deployment (Production). Redeploy after changing secrets. Client-side Vite apps still need VITE_ prefixes and a rebuild.
Can VibeRescue fix a Replit app?
Yes, if the source is on a public GitHub repo (or you grant access). Replit projects often export to GitHub; we run the fix in a sandbox and open a pull request. Full refund if the run cannot fix it.