> For the complete documentation index, see [llms.txt](https://docs.lingoql.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.lingoql.com/introduction/troubleshooting-deploys/build-failures.md).

# Build failures

A build failure means the app never finished compiling or preparing for startup.

Start with the first failing log line. That line is usually the real cause.

### Buildpack detection issues

LingoQL supports:

* `Railpack` — default
* `Nixpacks`

LingoQL can deploy apps supported by either buildpack.

If detection looks wrong, switch buildpacks and redeploy.

This helps when your repo is a monorepo, has a custom layout, or includes multiple runtimes.

Buildpack references:

* [Railpack docs](https://railpack.com)
* [Nixpacks configuring builds guide](https://nixpacks.com/docs/guides/configuring-builds)

### Dependency install failures

Dependency installs usually fail for one of three reasons:

* conflicting lockfiles
* unsupported runtime versions
* missing files required by the package manager

Use one package manager per app when possible.

Commit the matching lockfile.

Do not commit `node_modules`, virtual environments, or local caches.

### Runtime version mismatch

Pin the runtime version your app expects.

Examples include Node.js, Python, Ruby, PHP, Go, or Java.

If your app only works on a specific version locally, declare that version in the normal file your stack uses.

### Monorepo and wrong app root

The buildpack must see the app files it needs.

Check that the deployed directory contains the package manifest, lockfile, and source files for the app you want to build.

If the repo contains several apps, make sure you deploy the correct one.

### Native dependency failures

Some dependencies compile native binaries during install.

If a package fails only in cloud builds, try one of these fixes:

* switch from `Railpack` to `Nixpacks`, or back
* replace the package with a prebuilt or pure-language alternative
* remove optional dependencies you do not need in production

### Custom build commands with Nixpacks

If you need custom install, build, or start commands, add a `nixpacks.toml` file at the project root.

This is useful for frontend apps, SSR apps, monorepos, and custom output directories.

{% tabs %}
{% tab title="React static" %}

```toml
# nixpacks.toml for React (Vite or CRA)
[phases.setup]
nixPkgs = ["nodejs"]

[phases.install]
cmds = ["npm install"]

[phases.build]
cmds = ["npm run build"]

[start]
cmd = "npx serve -s build"
```

{% endtab %}

{% tab title="Next.js SSR" %}

```toml
# nixpacks.toml for Next.js
[phases.setup]
nixPkgs = ["nodejs"]

[phases.install]
cmds = ["npm install"]

[phases.build]
cmds = ["npm run build"]

[start]
cmd = "npm run start"
```

{% endtab %}

{% tab title="Nuxt 3 SSR" %}

```toml
# nixpacks.toml for Nuxt 3
[phases.setup]
nixPkgs = ["nodejs"]

[phases.install]
cmds = ["npm install"]

[phases.build]
cmds = ["npm run build"]

[start]
cmd = "node .output/server/index.mjs"
```

{% endtab %}

{% tab title="Vue static" %}

```toml
# nixpacks.toml for Vue or Vite static output
[phases.setup]
nixPkgs = ["nodejs"]

[phases.install]
cmds = ["npm install"]

[phases.build]
cmds = ["npm run build"]

[start]
cmd = "npx serve -s dist"
```

{% endtab %}
{% endtabs %}

For more information, please refer to Nixpacks here: <https://nixpacks.com/docs/guides/configuring-builds>

### Rust build fixes

Rust deploys can fail on native dependencies when the build target uses `musl` or when crates enable optional native features.

If your app needs OpenSSL on `musl`, use the vendored build:

```toml
openssl = { version = "0.10", features = ["vendored"] }
```

If you hit a `zstd` compile error through `actix-web`, disable default features and keep only what you need:

```toml
actix-web = { version = "4.11.0", default-features = false, features = ["macros"] }
```

These two changes resolve many Rust build failures on cloud deploys.

### Build works locally but fails on LingoQL

Run the production build locally, not the dev server.

Use a clean environment.

That means:

* install from the lockfile
* remove local caches
* confirm all required env vars are present

If local production build fails too, fix that before redeploying.

If the local build passes, compare the first failing dependency or compiler line from the deploy logs next.

That usually shows which package, crate, or optional feature needs to change.

### Quick recovery checklist

1. Redeploy with the other buildpack.
2. Pin the runtime version.
3. Commit the correct lockfile.
4. Add `nixpacks.toml` if you need custom commands.
5. Remove large or generated files from the repo.
6. Retry with a clean production build.

If the deploy fails during repository clone, see the GitHub limits page in this section.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.lingoql.com/introduction/troubleshooting-deploys/build-failures.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.