The build works on your computer but fails on the host

Find your cause

6 causes, most likely first

1. 1

   A different Node.js version

   How to tell: The log mentions an unsupported engine, a syntax error inside a dependency, or something like “requires Node >= 20”.

   Fix

   Check yours with node -v, then pin the same version on the host (the table below shows how).

2. 2

   The lockfile is missing or out of date

   How to tell: npm ci fails because package.json and package-lock.json are out of sync, or no lockfile was committed.

   Fix

   Run npm install on your computer and commit package-lock.json (or pnpm-lock.yaml, yarn.lock). Make sure it isn't in .gitignore.

3. 3

   Capitals in an import

   How to tell: “Module not found: Can't resolve './components/Header'”, though the file is there.

   Fix

   Build machines run Linux, where Header.jsx and header.jsx are different files. Make the import match the file name exactly. To rename only the capitals in git, use git mv header.jsx Header.jsx.

4. 4

   Warnings are treated as errors

   How to tell: “Treating warnings as errors because process.env.CI = true” (Create React App and some linters).

   Fix

   Fix the warnings. As a stopgap, set the build command to CI=false npm run build.

5. 5

   A tool that only your computer has

   How to tell: “command not found”, for example for hugo, sass or a CLI you installed globally.

   Fix

   Add it to the project with npm i -D so it's installed on every build. For Hugo, set HUGO_VERSION on Netlify, Vercel and Cloudflare Pages.

6. 6

   Environment variables are missing

   How to tell: The build stops on a missing API address or key.

   Fix

   Add the variables in the host's settings: .env files aren't committed, and shouldn't be.

Per host

Setting the Node.js version

99helpers

The build runs on your own computer, with the Node.js you already have.

GitHub Pages

The workflow picks it with setup-node's node-version (lts/* below).

Netlify

Set a NODE_VERSION environment variable, or add an .nvmrc file to the repository.

Vercel

Pick it under Settings → Build and Deployment → Node.js Version, or set "engines" in package.json.

Cloudflare Pages

Set a NODE_VERSION environment variable, or add an .nvmrc or .node-version file. The current build image starts on Node 22.

Questions

Also asked