Fix guides

Vercel or Netlify deploy fails but it builds locally

Build passes on your laptop, fails on the host. The common reasons AI-built apps fail to deploy and how to fix each one.

What you are seeing

• "Command npm run build exited with 1" on the host only.
• "Module not found" for a file that exists on your machine.
• Type errors or lint errors that never showed up in dev.

Why it happens

1. File name case mismatch. macOS and Windows ignore case, Linux build servers do not, so import Header from './header' fails when the file is Header.tsx.
2. npm run dev skips type checking and linting, but next build runs them.
3. A package is installed locally but missing from package.json, or the lockfile is out of date.
4. A different Node version on the host.
5. Env vars needed at build time are missing on the host.

How to fix it

1. Run the exact production build locally

rm -rf node_modules .next dist && npm ci && npm run build

2. Find case mismatches git is hiding

git config core.ignorecase false
git mv src/components/header.tsx src/components/Header.tsx

3. Pin the Node version

// package.json
"engines": { "node": "20.x" }

4. Read the first error, not the last

Scroll the build log up to the first red line. Later errors are usually fallout from that one.

How to know it is fixed

A clean npm ci && npm run build passes locally, and the next push deploys green.