Build failures

Build failures happen while the deployment status is Building, inside the sandbox, before any Function exists. Builds describes the pipeline. Use this reference to recover when it stops.

Read the deployment's Logs tab from the bottom. The last bracketed line names the stage that failed, and the message under it is the one to act on.

No framework was detected

Symptom. The build stops with No config file found and no framework detected.

Cause. The build looked in the project root for every accepted config filename, gigadrive.ts through nebula.json, found none, then read the package.json or composer.json in that same directory and found no dependency matching a framework detector. Detection covers both dependencies and devDependencies, and the project root is your root directory, not necessarily the repository root. A monorepo deployed without a root directory fails here, because the workspace manifest at the top of the repository lists no framework.

A directory that looks like a static site never reaches this error. An index.html at the project root is enough for the platform to write a two-line config and publish the tree as edge assets, which it records as No framework or config detected; deploying project root as static assets.

Fix. Point the root directory at the folder that holds the manifest, or commit a config file that declares what to deploy, as described in Configuration. The minimum that resolves is one Function or one assets directory:

version: 4
assets: public
functions:
  api/index.js:
    runtime: node-22

The root directory is wrong

Symptom. One of these, immediately after the source is fetched:

Root directory "apps/web" does not exist in the repository. Check your Build & Output Settings.
Root directory "apps/web" must be a directory in the repository. Check your Build & Output Settings.
Root directory "apps/web" must be a real directory inside the repository and cannot be a symlink.
Invalid root directory "../web". It must be a safe relative path without traversal or special characters.

Cause. The value is a path relative to the repository root, and it is validated before any command runs. A leading slash, a .. segment or a shell metacharacter is rejected outright. A symlink is rejected even when it points somewhere valid, and so is a path that resolves outside the extracted repository.

Fix. Correct Root directory under Settings, General, and leave it empty to use the repository root. The messages mention Build & Output Settings; that is the field they mean.

The root directory splits the build in two. Dependencies install from the repository root, so a workspace lockfile and a pnpm-workspace.yaml resolve normally. The build command, the config file and framework detection all use the root directory.

The lockfile is missing or does not match

Symptom. Either the log reads No package manager lock file found, skipping install and the build then fails on a binary that is not there, or the build succeeds and the deployment runs different dependency versions than your machine does.

Cause. The package manager comes from your packageManager field, then devEngines.packageManager, then the lockfile at the repository root, then npm as the fallback. The part that surprises people is what happens next: install runs the frozen form first and re-runs the plain form when that fails, so a pnpm install --frozen-lockfile that rejects a stale lockfile is followed by pnpm install --no-frozen-lockfile, which re-resolves and succeeds. A lockfile that disagrees with package.json does not fail the build. It changes what you ship.

With neither a lockfile nor a package.json, nothing is installed at all, and the first command that needs a dependency is where you find out.

Fix. Commit the lockfile belonging to the package manager you declared, and declare one with packageManager so a second lockfile in the tree cannot change the decision. A project with no lockfile also gets no build cache, because the cache key is built from the lockfile hash; see Build cache.

The build command exits non-zero

Symptom. The command's own output, then:

[build-and-package] Build and packaging failed
Build failed
Code failed with exit code 1

Cause. The build script in your package.json returned a non-zero exit code. That script is the whole contract, and no console field, API field or config key replaces it, as Build commands explains. When the script is missing entirely the log says No build script found in package.json, skipping build and the project is packaged as it stands, which produces a deployment that succeeds while serving an unbuilt tree.

One retry exists and it is narrow. A build whose output matches a transient network failure is run again, once, in the same sandbox, logged as Build lost a transient network dependency; retrying once in the same sandbox. Dependency installation is never retried.

Fix. Reproduce with the environment the sandbox sets rather than your shell's:

CI=true VERCEL=1 NITRO_PRESET=node-server pnpm run build

VERCEL=1 is set because ecosystem packages branch on it, and NITRO_PRESET=node-server keeps Nuxt output in .output instead of moving it. Both change what some frameworks emit, so a build that only fails in the sandbox usually fails locally once they are set.

If the build needs a value that only exists at deploy time, add it before deploying. Every environment variable resolved for the application is injected into the build, described in Environment variables.

The build runs out of memory or time

Symptom. The log stops part-way through the build, often after FATAL ERROR: ... JavaScript heap out of memory, sometimes with nothing after the last progress line, and the deployment fails.

Cause. The build sandbox has a fixed memory allocation that no setting exposes. When the kernel kills your build process the command exits non-zero and there is no platform message to explain it, because there was no error, only a dead process. A build that has not finished is stopped for a second reason after 25 minutes, when the sandbox is destroyed.

Fix. Lower what the build holds at once: cap the worker count of your bundler, move type checking out of the build script, and turn off production source maps. Setting NODE_OPTIONS as an environment variable raises the V8 heap limit, which helps only when that limit rather than the sandbox is what you are hitting.

For the 25-minute ceiling, the build cache is the lever that matters, since it carries the package-manager store and framework incremental state between deployments.

A dependency has to be compiled

Symptom. Installation fails inside a dependency's install script, with node-gyp, make or gcc in the output. Or the build succeeds and the Function then fails to load the module at runtime.

Cause. The build image is the official Node.js 24 image plus git, curl, unzip, zstd, php-cli, Composer, and npm, pnpm, yarn and bun. It carries no C or C++ toolchain, so a package that falls back to compiling from source because it publishes no binary for this platform cannot build.

The version mismatch is the subtler half. The build installs under Node.js 24 while your Function runs the runtime you declared, which tops out at node-22 and defaults to node-20. A native addon that picks or compiles its binary per Node ABI at install time is therefore loaded by a different Node than it was prepared for. An addon built against Node-API is stable across versions and loads fine. One built against a specific ABI does not.

Fix. Prefer a dependency that ships Node-API prebuilds, or a pure-JavaScript or WebAssembly alternative. When you must ship something compiled, build it outside the deployment, commit the artifact, and pull it into the Function with includeFiles, described in Entrypoints.

PHP projects hit the same wall through Composer: composer install runs against the image's php-cli, so a platform requirement the image does not satisfy stops the build there.

Failures that happen after your build command succeeds, including a missing entrypoint and the artifact size budget, are covered in Deployment errors.