## TL;DR

Exit code 1 means your framework's build broke; the Pages deploy step just reports it. The real error message is buried in the build log above the deploy failure. Run the exact same build command on your own machine to reproduce it, fix the underlying problem (usually a missing build-time env var or a node version mismatch), then redeploy.

```text
Build command failed with exit code 1
```

## Steps

1. Copy the build command from the Pages project settings (for example `npm run build`) and run it locally in a clean state:
```sh
rm -rf node_modules
npm ci
npm run build
```
Expected: the build fails locally with the real error message, which the deploy log truncated. That message is what you fix.

2. Check the node version. Compare your local version with the version pinned in the Pages project settings or the engines field:
```sh
node --version
```
Expected: it matches what Pages uses. A mismatch (for example local 22 vs Pages 18) explains builds that pass for you and fail there.

3. Check build-time environment variables. Anything the build reads (API base URLs, public keys, feature flags) must be set in the Pages project settings as build variables, not just in your local env file.
Expected: every variable the build references exists in the Pages dashboard.

4. Fix the underlying build error, commit, and redeploy:
```sh
wrangler pages deploy dist
```
Expected: the build step goes green and the deployment publishes.

## Use this when
- `wrangler pages deploy` fails with "build command failed with exit code 1"
- The failure is in the build phase, before anything uploads
- The same project builds on your machine but not on Pages

## Not for this skill when
- The build passes and the deploy step itself fails afterward
- The site builds but errors at runtime in the browser
- You are deploying a Worker with `wrangler deploy`, not a Pages project

## Variant phrasings
- cloudflare pages build failed exit code 1
- wrangler pages deploy build step error
- pages deployment build command exited with 1

## Why it happens

Pages runs your build in its own environment with its own node version and its own env vars. Anything your build assumes about your laptop (a newer node, a local .env file, a case-insensitive filesystem) breaks there while working for you, and all you see is the unhelpful exit code 1 wrapper.

## Edge cases
- Framework adapters for Workers (like the Next.js or Svelte adapters) have their own build quirks; check the adapter's docs when the raw framework build passes but the Pages build does not.
- A build that succeeds locally with a warm cache can fail on Pages with a cold one; the clean install in step 1 catches this.
- Large builds can hit the Pages build time limit rather than a code error; the log tail usually says so explicitly.
- Secrets and private env vars are not available at build time unless you mark them as build variables; runtime-only vars stay empty during the build.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_RY-kWraer3eFwsLb90MzYg