Cloudflare Pages "build failed" - Fix Pages Builds in CI

Cloudflare Pages could not complete the build: the build command exited non-zero, or the configured build output directory does not match where files were produced.

What this error means

The Pages deployment ends with build failed, sometimes adding that the build output directory was not found. The underlying error is in the build log above - a command failure or a path mismatch. It reproduces with the same command and Node version locally.

Failed: build command exited with code 1
# or
Error: Output directory "dist" not found.
Failed: error occurred while running build command

Common causes

Build command failed or env var missing

A compile error or a build-time variable set in the project settings but missing for the build makes the command exit non-zero.

Wrong build output directory or Node version

The configured output directory does not match the build (e.g. dist vs build), or an unset NODE_VERSION builds on a default that breaks the project.

How to fix it

Set the build command, output dir, and Node version

1. In the Pages project, set the Build command and the Build output directory to match your framework.
2. Add build-time variables (and NODE_VERSION) in the project’s Environment Variables.
3. Reproduce locally with the same command and Node version to read the real error.

Pin the Node version with a file

Commit a Node version file so Pages builds on the version your project needs.

# .node-version (or set NODE_VERSION in project settings)
20.11.1

How to prevent it

• Keep the Build output directory aligned with your build tool.
• Pin the Node version via .node-version or NODE_VERSION.
• Configure all build-time env vars in the Pages project settings.

Related guides