Deployment Troubleshooting
Diagnose source, build, startup, and health-check failures from the deployment detail page.
Deployment Troubleshooting#
Start with the exact stage and message shown on the deployment detail page. The most useful first distinction is whether the release failed while preparing/building source or after the application started.
Source and build failures#
| Symptom | Check |
|---|---|
| Dependency installation fails | Lockfiles, package manager selection, and the configured root directory. |
| Build command fails | Run the same production build locally and compare the command with the service configuration. |
| Static output is not found | Confirm the publish directory contains the generated index.html and assets. |
| Wrong service type | Use Static Site only for exported files; use Frontend App or Web Service for a server build. |
Startup and health-check failures#
| Symptom | Check |
|---|---|
| Health check timed out | The start command launches a persistent process, and the configured path exists. |
| Connection refused | The application listens on the injected PORT and binds to 0.0.0.0. |
| Health path returns an error | Use a route that is available without user authentication and succeeds after startup. |
| Next.js static deployment fails | If the project does not use output: "export", create a Frontend App instead. |
Make one correction at a time#
Update the source or configuration, then start a new deployment. Compare the new log with the previous one instead of changing several settings at once. If the same failure persists, collect the deployment URL, stage, and relevant log lines for support—remove secrets before sharing any output.