Deployment Troubleshooting
Diagnose source, build, startup, and TCP-readiness 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 or building source, or after the application actually started. Those two families of failures have completely different fixes: one is about project and dashboard configuration, the other is about application runtime behavior.
Use this page as a checklist rather than prose to skim. Match the symptom you see to the stage noted on the detail page, apply the listed check, redeploy once, and compare the new log to the previous one.
How to read a failure#
The deployment detail page separates a release into stages for exactly this diagnosis:
- Source → Dependencies → Build — did we correctly locate, install, and compile the code?
- Publish or start → TCP readiness — did the artifact produce the expected output, did the process launch, and did a container-network listener become reachable before the startup deadline?
A successful build followed by failed TCP readiness is a startup/configuration issue, not a source-build issue. Treating them the same slows down debugging because the two phases are fixed in different places (source/settings versus code and runtime contract).
Read stage output from the first error upward. Later warnings and timeouts are usually consequences of the earliest failure, not fresh root causes.
Source and build failures#
These are dash-before-code failures: the code might be perfectly correct, but the platform never got to start it because the chosen source, directory, or build command did not reproduce what builds locally.
| Symptom | What it means | Check |
|---|---|---|
| Dependency installation fails | The workspace install could not reproduce the local state | Lockfile, package manager selection, and the configured root directory. Does npm ci / pip install -r requirements.txt pass locally in the same directory you pointed NexHost at? |
| Build command fails | The production build itself errored | Run the same production build locally (npm run build, pip install …, go build, etc.) and compare the command with the service configuration character-by-character. A missing env value at build time is a common hidden variant — scope the variable correctly (see Environment Variables). |
| Static output is not found | NexHost built successfully but could not publish | Confirm the publish directory contains the generated index.html and assets after a local build. A common pair of mistakes is dist vs out, or pointing at the repository root instead of the package subdirectory in a monorepo. |
| Wrong service type | A static build was uploaded as if it were a server (or vice versa) | Use Static Site only for exported files (dist, out, build); use Frontend App or Web Service for a server build. Uploading .next to a Static Site is not supported. |
| Framework-detection warnings | The dashboard’s suggestion does not match the actual layout | Review the root directory and the detected framework; correct it explicitly rather than accepting a stale preset from a different project. |
Typical multi-step fix for a build failure:
- Re-run the exact build command locally in a clean checkout — not in a long-lived local branch where caches hide the issue.
- Confirm the publish directory listing (
ls dist,ls out,ls build) containsindex.html. - Mirror those values — branch, root directory, build command, publish directory, scoped environment variables — into the service configuration.
- Deploy one corrected attempt and read the new stage output against the previous one.
Startup and TCP-readiness failures#
These are after-code failures: the source was prepared and built, and the platform attempted to start the process, but the runtime could not reach a TCP listener.
| Symptom | What it means | Check |
|---|---|---|
| Startup readiness timed out | The process did not open a reachable listener before the startup window ended | The start command launches a persistent process and the process reaches its server listen call. A bare npm run build as a start command starts nothing and will always time out. |
| Connection refused | The process is running but its listener cannot be reached through the container network | Bind to `0.0.0.0`, not only 127.0.0.1. process.env.PORT is supplied as a compatibility default, but a fixed internal port such as 3000 is also safe because NexHost discovers it. |
| Next.js static deployment fails | The app needs a server but was shipped as static files | If the project does not use output: "export", it must not be a Static Site. Create a Frontend App instead and ship source — not .next or out. |
| Startup readiness intermittent / flaky | The service sometimes opens a listener before the deadline and sometimes does not | Move slow work out of the critical startup path and investigate dependency connections that can block initialization. |
Minimal reproduction when startup readiness blocks you:
# Reproduce locally with the same values the dashboard shows
PORT=3000 npm start
# confirm the process has opened a listener locally
ss -lnt | grep ':3000'If the process does not open a listener locally, NexHost cannot route it either.
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.
Why one change at a time matters: most deployment failures have two or three nearby causes (for example a wrong publish directory *and* a missing build variable). Fixing both in one edit hides which assumption was wrong; fixing them sequentially teaches you which had signal. The deployment history keeps every attempt, so the diff between two small edits is the precise diagnosis.
When filing a report with your team or support, include:
- The project and service name as shown in the dashboard.
- The deployment URL (the detail page, not a screenshot of its header alone).
- The failing stage name and a short excerpt of the surrounding log — with passwords, tokens, connection strings, and private hostnames redacted.
Related documentation#
- Logs — how to locate and read every stage’s output without leaking secrets.
- Deployments — the full release flow and how to restore a previous successful release.
- Environment Variables — build vs runtime scope so values arrive in the right phase.
- Frontend Apps / Web Services — runtime contracts for listener binding and startup.