Troubleshooting Failed Builds

When an Orbit build fails, the deployment detail page gives you the full log plus a categorised failure summary and a suggested fix. This guide walks through reading that page, the failures Orbit recognises by name, the failures it does not, and what to do when a build succeeds but the site is still wrong.

Reading the Failure

1. Open your project in Orbit.
2. Open the Deployments tab.
3. Click the deployment with status Failed.
4. Read the failure summary above the log first, then the log itself.

Orbit assigns every failure a category: Out of memory, Compile error, Test failure, Lint error, Install error, Network error, Timeout, or Unknown error. The category tells you which part of the pipeline to look at before you read a single log line.

There is also a Get AI diagnosis button. It reads the last 120 lines of the log along with the detected framework and failure category and returns a plain-language explanation.

If the build never started and is stuck on Queued, skip to the queued builds section below.

Failures Orbit Recognises By Name

These come with a specific suggested fix on the deployment page.

Common Failures By Phase

Dependency Install Fails

The Install phase errored.

• Wrong package manager. Orbit picks npm, yarn or pnpm from your lockfile. If more than one lockfile is committed, the choice may not be the one you expect. Delete the ones you are not using, or set Install command explicitly in Settings.
• Private registry. If a dependency comes from a private registry, the auth token has to be available at build time as an environment variable, and your .npmrc has to reference it.
• Node.js version mismatch. Some packages require a minimum Node version. Set Node.js version in Settings to the major version number: 18, 20 or 22.
• Out of memory on a large monorepo. Use npm ci rather than npm install, and consider a plan with a larger build machine.

Build Command Fails

The Build phase errored.

• TypeScript or lint errors. Orbit runs your build command exactly as written. If your build fails locally, it fails here.
• Missing build-time environment variable. A variable read during the build has to exist before the build runs, not just at runtime. Add it on the Env vars tab and redeploy. A build-time variable added after a deployment does not retroactively apply to it.
• Wrong root directory in a monorepo. Set Root directory in Settings to the app's path, for example apps/web.

Build Times Out

Builds are aborted at 30 minutes of wall-clock time on every plan. If yours consistently approaches that:

• Check the log for a process waiting on input. A build that prompts is a build that hangs.
• Avoid --legacy-peer-deps on a large dependency tree unless you need it.
• Make sure build cache is being used. The Liftoff and Apex plans include it; the deployment page shows Cache hit or Cold build.
• Move to a plan with more build vCPU. See Orbit Plan Limits.

The Build Never Starts

A deployment stuck on Queued is waiting for a build slot. The detail page shows your queue position and how many of your concurrent build slots are in use, and starts the build automatically when one frees up. Launch and Liftoff allow one concurrent build; Apex allows three.

You can see everything in flight across your account at Orbit, then Queue.

If a deployment sits queued with nothing else running, it is more likely being held rather than queued. Check for:

• Awaiting approval, if Require approval for production is on
• A deploy lock on the project
• A deploy freeze schedule blocking the current time or day
• CI required checks waiting on your pipeline
• Require staging success before production waiting on a staging deploy of the same commit

The Build Was Skipped Entirely

If a push produced no deployment at all, it was probably filtered on purpose:

• Ignored paths: every file in the push matched a pattern like *.md or docs/**
• Branch ignore patterns: the branch matched something like dependabot/*
• Root directory: nothing in the push touched the monorepo subdirectory for this project
• Branch previews off, and the push was not to production or staging

Build Succeeded But the Site Is Wrong

A green build and a broken site is almost always a configuration problem rather than a code problem.

404 on every page. The Output directory is wrong: Orbit published a folder that is not your build output. Check what your build actually writes. Common values are dist, .next, out, build and .output.

404 only on dynamic routes. The app needs a running server and is being served as static files. Turn on Server mode in Settings under Runtime. This is required for Next.js with SSR, Remix, Nuxt and anything else that is not a static export.

Assets 404 after a deploy, for users who were already on the site. They loaded the old page and are requesting old bundle URLs that no longer exist. Turn on Skew protection in Settings, which keeps the previous build's artifacts available for a retention window after a new deployment goes live.

Environment variable is undefined at runtime. Confirm the variable's scope actually covers this environment, and that the deployment postdates the change. The deployment detail page lists exactly which keys were injected at build time and diffs them against your current configuration.

Framework-by-framework build settings are in Configuring Your Build Command and Output Directory.

Retrying

On the failed deployment page:

• Retry build re-runs the same commit.
• More retry options, then Retry with cleared cache, deletes the build cache first.

You can also have Orbit retry for you. Build auto-retry in Settings re-queues failed builds caused by infrastructure errors such as a network failure or a timeout, up to three times. It deliberately does not retry code errors, so a compile, lint or test failure never loops.

Stopping a Bad Build Reaching Users

If a deploy has already gone live and broken something, roll back rather than trying to fix forward under pressure. Rollback promotes an already-built artifact and takes seconds. See Rolling Back a Deployment.

To stop further deploys while you investigate, click Lock deploys on the project. Push-triggered deploys are then skipped until you unlock, while manual deploys still work so you can ship the fix.

You can also make Orbit do this automatically: Auto-rollback on failure restores the last healthy deployment when a production deploy fails, and a Health check path restores it when the new deployment does not answer with a 2xx within 15 seconds.

Still Stuck

If the log simply ends with no error message, the build process was most likely killed: out of memory, or the build machine was reclaimed. Retry once. If it fails the same way twice, open a ticket from KPanel or email support@kapsulehost.com and include the deployment ID shown on the detail page.

Related Reading

• Viewing Build Logs
• Configuring Your Build Command and Output Directory
• Rolling Back a Deployment