Start here: preserve the evidence before changing anything
Write down the public URL, time of failure, deployment identifier, and one exact action that fails. Keep the previous deployment and a data backup available. Our recommended triage order below is an editorial workflow, not a diagnosis of your app or a promise that one setting will fix it.
| Symptom | Inspect first | Evidence to collect |
|---|---|---|
| Preview is also broken | Application behavior | Capture the first error in Preview before investigating publishing. |
| Build or startup fails | Publishing logs and commands | Compare the first failing command with the configured build and start commands. |
| Site loads; login or an API fails | Production configuration | Compare required variable names, callback hostnames, and the failing request. Do not copy secret values into a report. |
| Page loads; expected records are missing | Database environment | Identify which database each environment actually uses before copying or restoring data. |
| Uploaded files disappear after publishing | Persistent storage | Check whether the app writes to the deployment filesystem instead of durable storage. |
| Only one network cannot open the URL | Reachability | Compare another network before changing app code or DNS records. |
1. Distinguish a failed build from a failed server
In the Publishing pane, inspect Logs and the configured commands. A missing dependency is a different problem from a process that exits immediately. Replit's publishing guide says web servers must bind to 0.0.0.0. Explicit port mappings in .replit disable automatic detection: verify the local port and the documented external-port mapping rather than guessing a new port.
Check the deployment type against the workload. Static is for built files; Autoscale and Reserved VM run server workloads with different scaling behavior. Replit currently documents Static as incompatible with Agent-created apps. Scheduled deployments serve timed jobs, not an always-available website. Do not upgrade a plan before establishing which capability the application actually needs.
2. Compare configuration without exposing credentials
Use a two-column inventory of required environment-variable names and whether each is present in production. Add production Secrets in the Publishing pane; editor Secrets do not automatically carry over, as the publishing guide explains. The Secrets documentationexplains encrypted environment variables and warns against hard-coding credentials. Static deployments do not provide runtime Secrets; putting a private key into browser-delivered JavaScript is not an alternative.
For a login failure, record the failing request's status and destination hostname. For a payment failure, start with the provider's test mode. Do not disable authentication, widen CORS to every origin, or paste a connection string into an AI prompt to make an error disappear. Compare one suspected difference, make one approved change, and repeat the same check.
3. Empty production data is not automatically data loss
Replit's database guide distinguishes current Helium development infrastructure from legacy Neon projects. Publishing can create a separate production database; the legacy path has its own setup and optional development-data copy. Check the project's actual infrastructure and connection destination before following either path.
Inspect a harmless record in the intended environment. Do not replace production with development data just because a test account is absent. Schema changes made during development can be applied during publishing, so database isolation does not remove the need to review migrations. A rollback of application code is also not proof that its data was restored.
4. Verify recovery at the public URL
Replit warns that deployment-local files are not durable across publishing. Treat disappearing uploads separately from missing database rows; identify the storage destination before retrying the upload.
- Open the published URL in a fresh browser session and reproduce the original action.
- With an approved test account, check sign-in and a harmless create/read operation; refresh and verify the record persists.
- Compare the new log entry with the original error. A homepage returning HTTP 200 is not enough.
- Record the change and its result. If it failed, preserve that evidence and undo only your own reversible change.
Include the failing URL path, timestamp, deployment ID, expected result, actual status, redacted first error, and changes already tried. Exclude passwords, tokens, customer records, and unredacted environment dumps.
Keep the next decision narrow
Review the Replit Agent profile for product scope. If you are considering leaving the platform, use the code export and migration checklistbefore switching. Use Stack Builder to list the build, backend, hosting, and monitoring responsibilities you still need.