Skip to main content

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.

VideoWhen a Build Fails2:35

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.

  1. 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 KeyError for an environment variable.

  2. 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.

  3. 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.

  4. 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​

CategoryWhat it usually meansWhere the fix goes
Missing dependencyAn import has no matching entry in the requirements fileThe repository
Dependency conflictTwo pinned versions cannot both be installedThe repository
Syntax errorThe entry file does not parseThe repository
Missing secretThe app reads an environment variable that was never setSettings, Environment
Port conflictThe app serves on a port other than the framework'sThe repository, or the framework choice
Out of memoryThe install or the boot exceeded the tierSettings, Compute
Docker errorThe image could not be pulled or does not startThe wizard's source step
Auth failureThe access token cannot read the repositoryThe wizard's source step
Source errorThe repository or branch could not be clonedThe wizard's source step
Unknown errorThe log matched none of the aboveRead 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.

Describes the platform as of .

Was this page helpful?