Symptoms
- The deployment fails during the build
- The live address shows an error page
- It works in the preview but not when deployed
- Features that use API keys fail only on the live app
Why it happens
In the workspace, your app runs in development mode on a machine that already has everything set up. A deployment builds and starts the app again in a fresh environment.
If the build command, the start command, the port or the secrets are not set up for that environment, the deployment fails even though the workspace looks perfect.
Try this first
-
Read the deployment logs
Open the deployment and read the build and runtime logs. Look for the first error, not the last one.
-
Check the build and run commands
Make sure the deployment uses the right commands to build and start the app. A development command like npm run dev is not the same as a production start command.
-
Listen on the right address and port
Your server must listen on 0.0.0.0 and use the port the platform gives it, not a fixed port that only works in the workspace.
const port = process.env.PORT || 3000 app.listen(port, '0.0.0.0', () => { console.log(`Listening on port ${port}`) }) -
Make sure secrets reach the deployment
Check that every secret your app needs, like API keys and database addresses, is available to the deployment, not only to the workspace.
-
Pick the right deployment type
A static site and an app with a server need different deployment types. If your app has a backend, a static deployment will not run it.
When to stop and call a person
Get help if the logs point to database errors, if the app needs background jobs or scheduled tasks, or if you want to move it off Replit to your own hosting. Those usually need some changes in the code.
Questions people ask
Why does it work in the preview?
The preview runs your development setup. The deployment starts from a clean environment, so anything that only existed in the workspace is missing.
Do I need a paid plan to deploy?
Deployment options and limits change, so check Replit's current pricing page for what your plan includes.