> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sevalla.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> These are the docs for Sevalla, a platform for deploying applications, databases, static sites, object storage and load balancers. The dashboard is at https://app.sevalla.com.
> Bold text in steps is an exact dashboard label.
> To act on a Sevalla account, prefer the Sevalla MCP server (https://mcp.sevalla.com/mcp, see https://docs.sevalla.com/ai-agents/overview.md), then the Sevalla CLI (https://docs.sevalla.com/developer-tools/cli.md), then the REST API (https://api-docs.sevalla.com, OpenAPI spec at https://api.sevalla.com/v3/openapi.json).
> Every page index is at https://docs.sevalla.com/llms.txt.

# Troubleshoot builds and deployments

> Find why an application deployment failed and fix it: source code that can't be fetched, build errors per build strategy, Docker image errors, failed rollouts, failed jobs and time limits.

A deployment fails in one of its steps: while Sevalla fetches the source and builds the image, or while it rolls the image out to the processes. When a build fails, nothing changes and the previous version keeps running. This page lists the common failures by the message you see, with the cause and the fix.

## Find where a deployment failed

<Steps>
  <Step title="Open the deployment">
    In the sidebar, click **Applications**, then click the application. Click the **Deployments** tab, then click the failed deployment.
  </Step>

  <Step title="See which step failed">
    The steps at the top show **Queued**, **Build** and **Rollout**; the one marked **Failed** is where it stopped.
  </Step>

  <Step title="Read the logs">
    Open the **Build log** and scroll to the first red line. If the rollout failed, also open **Runtime logs**: they show what the new processes printed before they stopped.
  </Step>
</Steps>

Every limit and what happens when it's reached is in [Time limits and failures](/applications/deployments#time-limits-and-failures).

## The source code cannot be fetched

**Symptom.** The build log stops after `Fetching source code from github...` (or `gitlab`, `bitbucket`) with a Git error such as `remote: Repository not found.`, `fatal: could not read Username for 'https://github.com'` or `fatal: Remote branch main not found in upstream origin`.

**Cause.** Sevalla can no longer read the repository or the branch:

* The repository was deleted, renamed, moved to another account, or made private (for a public Git source).
* Sevalla lost access to it: the Sevalla app was uninstalled or its repository access was changed in GitHub, GitLab or Bitbucket, or the Git connection of the user who connected it was revoked.
* The branch was deleted or renamed.

**Fix.** Restore access in your Git provider (see [Git providers](/git/overview)), or point the application at the right repository and branch: on the **Settings** tab, click **Update source** in **Source**, and for the branch, update **Auto-deploy** or pick the branch when you [deploy](/applications/deployments#deploy-your-application). Then deploy again.

## No buildpack groups passed detection

**Symptom.** With the Buildpacks build strategy, the build log shows `ERROR: No buildpack groups passed detection.` and the build fails.

**Cause.** None of the buildpacks recognized the code in the build path. The usual reasons are a **Build path** that doesn't point at the application (in a monorepo, for example), files missing from the repository (such as `package.json`, `requirements.txt` or `composer.json`), or buildpacks that don't match the language.

**Fix.**

1. Check that the files your language needs are committed and pushed.
2. On the **Settings** tab, click **Update build strategy** and set **Build path** to the folder that holds the application, for example `apps/storefront`. Add the buildpacks your language needs.
3. Deploy again. If detection still fails, switch to [Nixpacks](/applications/builds/nixpacks) or [Railpack](/applications/builds/railpack), which detect more setups, or add a [Dockerfile](/applications/builds/dockerfile).

See [Buildpacks](/applications/builds/buildpacks) for the supported languages and files.

## Please switch to one of our newer heroku/builder images

**Symptom.** With the Buildpacks build strategy, the build log shows `Please switch to one of our newer 'heroku/builder:*' builder images`.

**Cause.** The application uses a Heroku builder image that Heroku no longer supports.

**Fix.** On the **Settings** tab, click **Update build strategy**, pick **heroku/builder:24** in **Pack builder**, click **Update build strategy**, and deploy. Check that your language version is supported by that builder.

## The build fails on the language version

**Symptom.** With Nixpacks or Railpack, the build fails while it installs the language, or uses a version your code doesn't support. It often works with Buildpacks but not with Nixpacks.

**Cause.** The builder picked a default version because the repository doesn't declare one.

**Fix.** Declare the version in the repository, for example `"require": { "php": "~8.3.0" }` in `composer.json` for PHP, or a `.python-version` file for Python, then deploy again. Each builder's page lists the files it reads: [Nixpacks](/applications/builds/nixpacks), [Railpack](/applications/builds/railpack), [Buildpacks](/applications/builds/buildpacks).

## npm run build did not complete successfully: exit code 126

**Symptom.** The build fails with a line like:

```text theme={null}
ERROR: failed to solve: process "/bin/bash -ol pipefail -c npm run build" did not complete successfully: exit code: 126
```

**Cause.** Exit code `126` means a command was found but couldn't run. The usual reason is a `node_modules` (or PHP `vendor`) folder committed to the repository, whose binaries don't run in the build environment.

**Fix.** Remove `node_modules` and `vendor` from the repository, add them to `.gitignore`, push, and deploy. The build installs dependencies itself.

## Skip pruning because NODE\_ENV is not production

**Symptom.** A Node.js build with Buildpacks logs a warning that it skipped pruning development dependencies because `NODE_ENV` isn't `production`.

**Cause.** Sevalla doesn't set `NODE_ENV`, so the buildpack keeps development dependencies in the image.

**Fix.** Add an [environment variable](/applications/environment-variables) `NODE_ENV` with the value `production`, available during the build and at runtime, and deploy again.

## Image does not exist or incorrect authentication

**Symptom.** A deployment of a Docker image fails before the rollout with `"<image>" image does not exist or incorrect authentication.`, or `Docker registry authentication failed. Please verify your registry credentials - the token may be expired or invalid.`

**Cause.** The image name or tag is wrong, the image is private and the application has no registry credential, or the credential's token expired or lost access.

**Fix.** Check the image and tag on the **Settings** tab under **Source**. For a private image, create or renew a [registry credential](/applications/docker-images#add-a-registry-credential) and select it with **Update source**. Make sure the image is built for `linux/amd64`. Then deploy again.

## Failed to deploy, check the entrypoint

**Symptom.** The rollout fails with `Failed to deploy <process>. Please check the entrypoint.`

**Cause.** The process's start command runs a program that doesn't exist in the image (`command not found`), for example `yarn` in an image that only has `npm`, or a script that isn't committed.

**Fix.** On the **Processes** tab, click **⋯** on the process, then **Update process**, and correct the **Custom start command**, or clear it to use the image's default command. For a Dockerfile build, check its `CMD` or `ENTRYPOINT`. Then deploy again.

## Failed to deploy a process

**Symptom.** The rollout runs for a while, then fails with `Failed to deploy <process>.`

**Cause.** The new instances of that process didn't become ready within 20 minutes, so Sevalla rolled the process back to its previous version. The process kept crashing (an error at startup, a missing environment variable, a database it can't reach), ran out of memory, or failed its [readiness or liveness probe](/applications/processes#health-checks).

**Fix.**

1. Open the deployment's **Runtime logs**, or **App health** on the application, to see why the instances stopped. [Troubleshoot runtime errors](/applications/troubleshooting/runtime-errors) explains the exit codes.
2. Fix the cause: the code, the [environment variables](/applications/environment-variables), a larger [instance size](/applications/scaling#change-the-size-of-a-process), or the probe's path, port and **Initial delay**.
3. Deploy again.

A process with no readiness probe counts as ready as soon as its container starts, so a server that listens on the wrong port can deploy successfully and then return errors. See [Troubleshoot HTTP errors](/applications/troubleshooting/http-errors).

## A job has failed or timed out

**Symptom.** The build log shows `<job name> has failed` or `<job name> has timed out`, and the deployment fails.

**Cause.** A [job](/applications/processes#jobs) exited with an error, or was still running after about 5 minutes. When it ran **Before deployment**, the other processes stayed on the previous version.

**Fix.** Read the job's lines in the deployment's **Runtime logs** (pick the job in **Process** on the **Logs** tab), fix the error, and deploy again. Move work that takes longer than a few minutes to a [background worker](/applications/processes#background-workers) or a [cron job](/applications/processes#cron-jobs).

## The deployment ran out of time

**Symptom.** The deployment fails after 30 minutes without an error of its own.

**Cause.** A deployment, from the clone to the end of the rollout, has 30 minutes. A slow build (large dependencies, assets compiled from scratch) or a slow rollout used them up.

**Fix.** Turn on the build cache and trim the build; see [Build settings](/applications/builds/overview#build-settings). For a slow rollout, see [Failed to deploy a process](#failed-to-deploy-a-process).

## An ongoing action blocks the deployment

**Symptom.** The build log shows `There is an ongoing action that blocks the <process> deployment. Trying to fix it...`

**Cause.** A previous change to that process was still being applied. Sevalla resolves it and continues; no action is needed unless the deployment then fails.

**Fix.** If the deployment fails, deploy again.

## Environment variables do not have the expected value

**Symptom.** A variable is empty or different from what you set during the build, or the application reads a value with extra backslashes or quotes.

**Cause.** During the build, a `$` in a value is expanded by the build shell. At runtime, values are passed literally, so escape characters you added yourself (`\,`, `\"`) stay in the value.

**Fix.** Remove manual escaping, make variables whose values contain `$` available during runtime only, and check the values with `printenv` in the [web terminal](/applications/web-terminal). See [Special characters](/applications/environment-variables#special-characters).

## Reproduce a build on your computer

Building locally with the same tool shows errors faster than repeated deployments:

<Tabs>
  <Tab title="Nixpacks">
    Install [Nixpacks](https://nixpacks.com/docs/install), then run in the application folder:

    ```bash theme={null}
    nixpacks build . --name storefront
    ```
  </Tab>

  <Tab title="Railpack">
    Install [Railpack](https://railpack.com/installation), then run in the application folder:

    ```bash theme={null}
    railpack build .
    ```
  </Tab>

  <Tab title="Buildpacks">
    Install the [pack CLI](https://github.com/buildpacks/pack), then run in the application folder:

    ```bash theme={null}
    pack build storefront --path . --builder heroku/builder:24
    ```
  </Tab>

  <Tab title="Dockerfile">
    ```bash theme={null}
    docker build --platform linux/amd64 -t storefront .
    ```
  </Tab>
</Tabs>

If you're still stuck, [contact support](/support/get-help) with the application's name and the deployment's link.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.