When a build fails
A build that fails keeps you on the same page and shows what it found rather than a stack trace to scroll. This page is the reference for what it tells you.
Who can use it: the Builder role or higher.
Recorded on .
A failed build in four steps
The video above ships a build that fails at boot and follows it to the fix; the sections below are the reference for what the page shows.
- Ship and watch the build
Ship app on the Review step starts the build. The build view streams the log stage by stage, with the five stages on the right and Cancel build while it runs. This build clones, installs and pulls the runtime image, then fails when the app boots on a
KeyErrorfor an environment variable. - Read the failed view
The badge names the stage that failed and the category the log matched, here Missing secret; the heading is the platform's reading of the cause, and the last twelve log lines follow. Suggested fixes come numbered, the first recommended, each with Apply fix or Learn how.
- Take the fix where it goes
A missing secret is fixed in Settings, under Environment. Open the app from its Failed row, add the variable the log named with its value, and Save changes; it applies on the next restart.
- Know a lost stream from a failure
If the log goes quiet the page says it lost the connection and reconnects; after 45 seconds it says stream lost. That is the connection, not the build: the app's page and its deploys list say whether it finished.
What the page shows
The heading gives the app and how long the build ran. Under it sits the platform's own reading of the cause, taken from the log rather than translated, with a badge naming the stage that failed and, where the log matched a known pattern, one of ten categories. Only the stages that actually ran are ticked. The last twelve log lines follow.
Suggested fixes come next, numbered. Each carries either Apply fix, where the platform knows what to change, or Learn how, where it does not. Apply fix does one of four things depending on the fix: opens the app's settings, opens the file in a code workspace, reopens the wizard, or opens a link.
Retry build starts a new build of the same app and the view follows it. View raw logs opens the full log, and Back to App Studio returns to the list.
Two things on this page are not built. The side panel's recent builds list says the history view ships next sprint, and the three help links below it do not go anywhere.
The categories
| Category | What it usually means | Where the fix goes |
|---|---|---|
| Missing dependency | An import has no matching entry in the requirements file | The repository |
| Dependency conflict | Two pinned versions cannot both be installed | The repository |
| Syntax error | The entry file does not parse | The repository |
| Missing secret | The app reads an environment variable that was never set | Settings, Environment |
| Port conflict | The app serves on a port other than the framework's | The repository, or the framework choice |
| Out of memory | The install or the boot exceeded the tier | Settings, Compute |
| Docker error | The image could not be pulled or does not start | The wizard's source step |
| Auth failure | The access token cannot read the repository | The wizard's source step |
| Source error | The repository or branch could not be cloned | The wizard's source step |
| Unknown error | The log matched none of the above | Read the log |
The category is a match against the log text, not a verdict from the runtime. Where it says unknown, the cause line above it is still the platform's best quotation of what went wrong.
The failure that is not a failure
An app can build, boot, serve traffic correctly and still be marked Failed. It happens when the health probe asks for a path the app does not have.
The platform probes a default per framework, for example /_stcore/health for Streamlit, while FastAPI and a Docker image get a plain TCP port check instead. If your app does not answer the path being probed, the pod never reports ready. Setting Health check path in the wizard, or in the app's compute settings afterwards, is the fix, and it is worth setting deliberately rather than leaving to the default: a real health endpoint also catches an app that is running but broken, which a port check never will.
A build that was cancelled
A cancelled build is stored as a failure with a fixed reason saying it was cancelled by a user, and the deploys list shows it as cancelled rather than failed. Nothing was rolled back, because nothing had been promoted. Ship again from the wizard.
When the page says it lost the stream
A dropped stream reconnects by itself first. If there is still no stream after 45 seconds, the page says it lost the stream and offers View app status, Retry build and Back to App Studio; none of them cancels the build. That message is about the connection, not the build. The build may well have finished; the app's own page and its deploys list are the place to check before you start another one.