> ## Documentation Index
> Fetch the complete documentation index at: https://docs.replit.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshoot deployments

> Diagnose failed publishing, startup and health-check failures, 502 responses, and Preview differences using logs before changing your published Replit app.

Check [Replit Status](https://status.replit.com), then identify where the failure
occurs: building, starting, or serving requests. Keep the failed deployment's logs
before retrying. See [Publishing troubleshooting](/build/troubleshooting) for
configuration details.

## Publishing fails during the build

1. Open **Publishing** and the failed deployment's logs.
2. Find the first actionable error, not only the final “build failed” message.
3. Check the build command, dependency installation, and referenced file paths.
4. Check whether required environment variables are configured for publishing.
   A working Preview does not verify production configuration.
5. Fix the identified issue, publish again, and compare the new logs.

If the run command is missing, check the publishing configuration and save the
intended command before retrying. Do not repeatedly republish an unchanged build.

## The build succeeds, but startup or health checks fail

Confirm that the run command starts a long-running server rather than a build
process that exits. For a web server, check its bind address and port configuration.
It should accept external connections rather than listen only on `localhost`.

Read [Port configuration](/build/troubleshooting) before changing explicit port
mappings. Check startup logs for missing production secrets, database failures,
or exceptions before the server begins accepting requests.

Do not remove authentication or application checks indiscriminately to make a
deployment pass. Diagnose the failing route or startup dependency.

## The published app returns 500 or 502

1. Reproduce one request and record its time and affected URL.
2. Inspect runtime logs around that time for exceptions, crashes, or restarts.
3. Check whether a required database or external API is reachable.
4. Compare failures with CPU and memory usage in
   [Monitoring](/features/publishing/monitoring-a-deployment).

A 500 or 502 is a symptom, not proof of a specific cause. See
[Networking and app errors](/help/networking-and-app-errors).

If the `replit.app` URL works but the custom domain fails, use the
[domain guide](/help/troubleshooting/domains). If only sign-in fails, use the
[authentication guide](/help/troubleshooting/auth).

## Preview works, but the published version does not

Compare the published version, build and run commands, production secrets,
database selection, and auth configuration. Updating a workspace secret does
not establish that the published app uses the same value.

After a targeted production configuration change, publish it and test again.
Before redeploying an older version, check whether it is compatible with the
current database schema. Redeploying code is not a database restore.

## Publishing is blocked by a workspace policy

For “Public deployments are not allowed for this workspace,” ask your workspace
administrator to review publishing policy. Do not bypass the policy by moving
code or data to a personal workspace.

## Still failing?

Send Support the project URL, deployment type, failed phase, sanitized build or
runtime logs, and the time of a failing request. Say whether Preview and the
published URL behave differently. Follow the
[support checklist](/help/troubleshooting/overview#when-to-contact-support).