Why does an import work on my Mac but say module not found on Vercel?

macOS and Windows usually ignore capitalisation in file paths, so ./Header finds header.tsx locally. Vercel builds on Linux, which is case-sensitive, so the same import fails with module not found until the casing matches exactly.

How do I tell if a file is missing on Vercel because it was never committed?

Run git status and look for untracked or ignored files your app needs, and check .gitignore for a rule that excludes them. Secrets in .env.local are the exception — those belong in Vercel's Environment Variables settings, not in git.

Why should I delete .next and rebuild locally if it already works?

Your laptop reuses earlier build output, so a stale cache can mask a broken clean build. Delete .next, reinstall, and run a fresh build locally — if it fails there too, you have reproduced Vercel's clean start where debugging is faster.

Works locally, fails on Vercel — build or runtime errors after deploy

Filed under Deployment failures

The fix, fast

When a site works locally but fails on Vercel, the code is usually fine and the environment is different: check file-name capitalisation first, then missing environment variables on Vercel, then the Node version, then files that exist on your machine but were never committed to git. Work through that checklist in order, reading the first error in the Vercel build log, and redeploy after each single fix.

Why this happens

Your laptop and Vercel are not the same computer, and the differences are quiet ones. Your Mac or Windows machine usually treats file names as case-insensitive, so ./Header happily finds a file called header.tsx. Vercel builds on Linux, which is case-sensitive, so that same import fails with module not found. Your local machine also carries state Vercel never sees: a .env.local file, globally installed tools, a warm build cache that can hide a broken clean build, and files you created but never committed.

Vercel, by contrast, starts fresh every time. It clones exactly what is in git, installs exactly what your lockfile says, uses the Node version set for the project, and builds from scratch. Anything that only exists in your local setup — a variable, a generated file, a differently-cased filename that git never properly recorded — is missing there, even though nothing looks wrong at home. That is actually useful once you see it that way: a Vercel failure is a checklist of hidden local assumptions, and most projects hit the same four or five.

Symptom on Vercel	Most likely cause
Module not found for a file that exists	Capitalisation mismatch in the import path
Build passes, app breaks or a value is undefined	Environment variable missing in Vercel
Build fails with a syntax or engine error	Node version mismatch
File, image, or data missing at build or runtime	File never committed to git

The fix, step by step

Read the first error in the Vercel build log, not the last. In the Vercel dashboard, open the failed deployment and its Build Logs. Scroll to the first red error — later errors are usually fallout from that one. Note the exact file, line, and message before changing anything. Also note whether it failed during build or only at runtime when you visit the page, because that split tells you whether to look at imports and variables or at server code and data.
Fix capitalisation mismatches in imports. Compare every part of the failing import path to the real file name on disk, letter by letter, including the folder names. Linux requires an exact match. If you need to rename a file only by case, a plain rename often does not register in git — use git mv so git records it.
```
// File on disk: components/header.tsx
// Fails on Linux:
import { Header } from "./components/Header";
// Works:
import { Header } from "./components/header";

// Recording a case-only rename in git:
git mv components/Header.tsx components/header.tsx
```
Copy every needed environment variable into Vercel. Your .env.local is deliberately not committed, so Vercel has none of those values unless you add them. In the Vercel dashboard, open Project Settings, then Environment Variables, and add each name from your local file for Production and Preview as needed. Then redeploy — a variable added after a build does not affect that build. Never paste a local file's secrets into code to work around this.
Match the Node version. Check the version you run locally, then set the same major version on Vercel in Project Settings under Node.js Version, or declare it in package.json so both places agree. A mismatch can surface as a strange syntax error, a package that refuses to install, or a build that behaves differently for no obvious reason.
```
# Your local version:
node -v

# package.json — declare what the project expects:
{
  "engines": { "node": "20.x" }
}
```
Hunt for files that exist locally but not in git. Run git status and look for untracked or ignored files your build depends on: generated files, uploaded images, a local data file, or a config you created and forgot. Anything Vercel needs must be committed (except secrets in .env.local, which belong in the dashboard instead). Also check .gitignore — an over-broad rule like *.json or a folder name can silently exclude a file your app expects.
```
git status
# Is the file your code needs listed as untracked or ignored?
git check-ignore -v path/to/file
```
Reproduce a clean build locally, then redeploy once. Delete your local build output and dependency cache effect by running a fresh install and build, which is the closest you can get to Vercel's clean start on your own machine. If it fails locally now, fix it there where debugging is faster. If it passes, redeploy on Vercel with the cache cleared (Redeploy and untick the build cache option) so you are testing your fixes, not a cached earlier attempt.
```
rm -rf .next
npm install
npm run build
```

Give your AI this prompt

My app works locally but fails on Vercel.

Here is the FIRST error from the Vercel build log (or the runtime error if the build passes): [paste it, plus whether it fails at build time or when visiting the page]
My stack is: [e.g. Next.js App Router], my local Node version is: [paste node -v output]

Please triage in this order and report what you find at each step before changing anything: 1) import paths whose capitalisation does not exactly match the file on disk (Linux is case-sensitive, and case-only renames need git mv), 2) environment variables that exist in my .env.local but are missing in Vercel Project Settings > Environment Variables, 3) Node version mismatch between local, package.json engines, and Vercel settings, 4) files my code needs that are untracked, ignored, or missing from git, 5) whether a clean local build (fresh install, no .next cache) reproduces the failure.

Constraints: make one change at a time, do not commit .env.local or any secret, do not rewrite unrelated files, and tell me which checklist item caused it.