"It Worked on My Windows Laptop!"
One of the most frustrating experiences in web development is when code runs perfectly during local development, but crashes instantly once pushed to a Linux production container.
The Usual Suspects:
1Linux Case-Sensitive File Systems:
Windows and macOS have case-insensitive file systems by default. If your component is named
Header.jsx and you write import Header from "./header", it compiles locally on Windows without error.But on a Linux CI/CD runner (GitHub Actions, Vercel), it fails with:
Cannot find module './header'.*Fix:* Strictly enforce lowercase or PascalCase consistency across all filenames and configure eslint import rules.
2Missing Environment Variables on Edge Runners:
A secret key exists in your local
.env file (which is git-ignored), but was never added to the production hosting dashboard.*Fix:* Use an environment validator like
t3-oss/env-core or Zod at application bootstrap so the server crashes immediately with an explicit error rather than silently failing during customer transactions.3Hydration Mismatches in SSR:
Comparing client and server render outputs. Using
new Date().toLocaleTimeString() or window.innerWidth directly in React component rendering generates different HTML on the server than on the browser, causing React hydration warnings.