Troubleshooting deploys

Most failed deploys fall into a handful of buckets. This page walks through the ones we see most often, in roughly that order, and points you at the fix for each. Every deploy keeps a full Build log and Deploy log - open the failed deployment to read the exact error your build or container reported.

Build failures

The build step is where deploys fail most. orkestr builds your image in a sandboxed builder, so the build runs with only what's in your repo and the environment variables you've configured.

A build-time environment variable is missing

Some frameworks read environment variables at build time, not just at runtime. Next.js bakes any NEXT_PUBLIC_* value into the bundle during the build, and tools like Supabase or Stripe clients often expect their keys to be present then too. If the variable isn't set, the build fails with an error that references that key.

• Open your environment and add the variable under Environment Variables, then deploy again.
• Variables set on the project are inherited by every environment; set them per-environment when staging and production differ.
• The variable must exist before the deploy that needs it - adding it afterwards won't retro-fix an image that already built without it.

The build ran out of memory

Larger frameworks (Next.js, Nuxt) can exhaust the builder's memory while compiling, which shows up as an out-of-memory kill or a "build worker exited" message. This is the build step running short on memory, not your running app.

• On Pro and Team, turn on Memory boost for the environment and redeploy to give the build more headroom.
• Removing unused dependencies and large assets from the repo also lightens the build.

The build timed out

Builds have a time limit. A build that runs long usually means a very large dependency tree or image. Trimming dependencies and using your framework's production build settings keeps builds well under the limit. If a build consistently times out, reach out and we'll take a look.

The build reported an error

If your framework's build step itself errors out (a failed compile, a bundler error, a failed npm / pnpm install), orkestr surfaces that error verbatim in the Build log. The last lines point to the file and reason. A build that succeeds locally with the same commit and the same environment variables will succeed here too.

The app didn't pass the health check

After the image is built and the container starts, orkestr checks that your app answers on its port. If it doesn't respond in time, the deploy is marked failed and your previous version is kept live, so there's no downtime.

• Confirm the port your app listens on matches the port orkestr expects. Bind to the PORT environment variable and listen on 0.0.0.0, not just localhost.
• Make sure every runtime environment variable the app needs to start (database URLs, API keys) is set on the environment.
• Check the Deploy log and the container logs for a startup error or crash loop.

No framework detected and no Dockerfile

orkestr auto-detects your framework and generates a Dockerfile when your repo doesn't ship one. If detection can't find a known framework and there's no Dockerfile to fall back on, the deploy stops early.

• Add a Dockerfile at the repo root - if one is present, orkestr builds it as-is and detection is skipped.
• If your app lives in a subdirectory, make sure the project points at the right path.
• See the supported frameworks in the Deployments docs.

The repository couldn't be cloned

The first step clones your repo at the environment's branch. A clone failure usually means an access or size issue.

• For private repos, connect the matching provider (GitHub, GitLab, Bitbucket, or Codeberg) in Settings. Without a connection, only public repos can be cloned.
• If you recently changed the branch name, confirm the environment's branch still exists.
• Very large repositories can be slow to clone - reach out if a clone keeps timing out.

The container failed to start

If the image builds but the container won't start, the cause is usually a missing runtime variable or a start command that exits immediately. Check the Deploy log for the Docker error and the container logs for the first crash.

Temporary capacity

Occasionally a deploy can't be placed right away. This is transient - retry the deploy in a minute. If it persists, let us know and we'll sort it out.

Still stuck?

If none of the above gets you unblocked, come chat with us - share the deployment and what you're seeing, and we'll help you work through it.