Chapter 11 — Casebook I: "It Works on My Machine"

Environment, Build, Time Zone, Session and Version Bugs — Investigated End to End

Part 3: The Casebook. Prerequisites: Parts 1 and 2 (Chapters 1–10).

How to Use the Casebook

Parts 1 and 2 gave you the method and the instruments. The casebook puts them to work on the bugs engineers meet again and again. Every case has the same shape:

1. Symptom — what was reported, as vaguely as it usually is.
2. First five minutes — the checks to run before forming opinions.
3. Hypotheses — ranked, each with the cheap check that confirms or kills it.
4. Root cause — the deepest thing that, once fixed, prevents the whole class of bug.
5. Fix and prevention.
6. What an interviewer is testing — because each of these is also a classic interview question.

Some cases are investigations you play. You see the symptom and several possible checks; pick one and you see what it would actually show. Dead ends cost time. Good checks move you forward. Try to finish each one on the shortest path — and when you are done, open "what the other checks would have found", because the dead ends teach as much as the right answers.

Why "it works on my machine" happens at all

"It works on my machine" is never a statement about the code alone. It is a statement that your environment and the failing environment differ, and the bug lives in one of the differences. This chapter's cases are all instances of the differential diagnosis from Chapter 1: list what differs, then eliminate.

Case 1 — "Production Calls localhost"

Symptom. A newly deployed frontend shows "Couldn't load your orders." It worked in local development and in yesterday's preview.

What the case teaches

The key distinction is build-time configuration versus runtime configuration:

Two follow-on bugs from the same distinction:

• The secret in the bundle. Someone prefixes an API secret with NEXT_PUBLIC_ "to make it work in the browser." It is now public, in every user's browser. Rotate it.
• The silent fallback. ?? 'http://localhost:4000' turned a loud configuration error into a confusing runtime failure. Defaults for required configuration hide bugs; prefer failing fast.

What an interviewer is testing: whether you check what the browser actually sent before reading code, and whether you know where configuration lives at each stage of a build.

Case 2 — "The Build Fails Only in CI"

Symptom. npm run build succeeds on every developer's Mac. In CI (and on the hosting platform) it fails with:

Module not found: Can't resolve './components/userAvatar'

First five minutes. Read the error literally (Chapter 2): the path it cannot resolve is ./components/userAvatar. List the folder in the repository as CI sees it.

Hypotheses.

Root cause. macOS (and Windows) file systems are case-insensitive by default, so ./components/userAvatar finds UserAvatar.tsx. Linux file systems are case-sensitive, so the same import fails. CI and production run Linux. A common trigger: someone renames userAvatar.tsx to UserAvatar.tsx on a Mac, and Git does not record the case-only rename, so different machines disagree about the file's real name.

Fix. Make the import match the file exactly. To rename a file's case so Git records it: git mv userAvatar.tsx UserAvatar.tsx.

Prevention. Enable a lint rule or TypeScript's forceConsistentCasingInFileNames, and make sure CI runs the same build as production on every pull request.

The wider family. Other "builds on my machine" causes: a different Node version (pin it with an engines field or .nvmrc, and use the same version in CI); a package installed globally on your machine but missing from package.json; a devDependency used at runtime and missing when production installs only dependencies; a file ignored by .gitignore that exists only on your disk.

What an interviewer is testing: that you treat "only in CI" as a list of environment differences and check them, instead of retrying the build.

Case 3 — "Deadlines Are One Day Early for US Users"

Time and place: the rest of the family

• Dates vs instants. A birthday, a due date or a holiday is a calendar date — the same everywhere. A meeting start or a log timestamp is an instant — one moment, shown differently in each zone. Store and handle them as different things.
• Server in UTC, laptop in IST. Code that formats dates on the server uses the server's zone (usually UTC), so "today" can be a different date on the server than for the user.
• Locale. toLocaleString() without arguments formats numbers and dates differently per user: 1,234.5 in one locale is 1.234,5 in another; parsing user input with the wrong locale corrupts values.
• Daylight saving time. An hour that happens twice (or not at all) once a year breaks schedules and "add 24 hours" logic. Chapter 14 covers time-based bugs in depth.

What an interviewer is testing: whether you reproduce by changing the environment to match the user's rather than asking for more screenshots — and whether you know the difference between a date and an instant.

Case 4 — The Hydration Error That Only Happens in Production

Symptom. After deploying, the error tracker shows Hydration failed because the server rendered HTML didn't match the client (or Minified React error #418) on the dashboard page. Nobody can reproduce it locally.

First five minutes. Production React errors are minified (Chapter 2): open the error's URL to get the full message, then look at which text mismatched. The error tracker's breadcrumb shows the server rendered Last updated 10/10/2026, 8:30:00 AM and the client rendered Last updated 10/10/2026, 2:00:00 PM.

Hypotheses.

Why it works locally. On your laptop, the "server" (your dev server) and the browser run on the same machine, with the same time zone and locale, so both render the same string. In production, the server runs in UTC in a data centre and the browser runs wherever the user is. This is the time-and-place difference from Case 3, surfacing as a rendering bug.

Fix. Render values that depend on the viewer's time zone or locale only on the client (format after mount), or format them on the server in an explicit, fixed zone and locale so both sides agree. For a timestamp that must appear in the user's local time, rendering it in a client-only component is the honest fix.

Prevention. Run your local server with TZ=UTC to match production, so the mismatch appears on your machine first.

What an interviewer is testing: that you know what hydration is, why server and client must produce identical HTML, and which inputs can differ between them.

Case 5 — "Users Get Logged Out at Random"

Symptom. After the API was scaled from one instance to three, users report being logged out "randomly" — sometimes twice in a minute. It never happens locally.

First five minutes. Logs filtered by one affected user's ID show 401 session not found — always on instance-b or instance-c, never on the instance where they logged in.

Root cause. The session store was the default in-memory store, which lives inside one process. Scaling out turned "one process holds all sessions" into "each process holds a third of them."

Fix. Move sessions to a shared store (Redis or the database), or use self-contained signed tokens that any instance can verify. Sticky sessions (the load balancer pins a user to one instance) hide the problem but break again whenever an instance restarts or scales down.

Other causes of random logouts, and their tells:

What an interviewer is testing: stateless versus stateful services — the reason a system that works on one machine breaks when scaled horizontally.

Case 6 — "Failed to Fetch Dynamically Imported Module"

Symptom. Minutes after every deploy, the error tracker fills with ChunkLoadError: Loading chunk 482 failed or TypeError: Failed to fetch dynamically imported module. Reloading the page fixes it for that user. You never see it yourself.

First five minutes. Look at the failing URL: /_next/static/chunks/482.4f1c9a.js returns 404. The current deploy's chunk for that route is 482.b77e21.js.

Root cause — version skew. Modern bundles split code into chunks loaded on demand, with a content hash in each filename. A user who opened the app before the deploy has the old page in memory, which knows the old chunk names. When they navigate to a new route, the old page asks for an old chunk. If the deploy deleted the old files, the request 404s. You never see it because you always reload after deploying.

Fix and prevention.

• Keep old assets available for a while after each deploy (immutable, versioned deployments do this automatically; self-hosted setups that overwrite one folder do not).
• Recover gracefully: catch chunk-load failures and do a full page reload, once, so the user gets the new version.
• Handle API skew too. The same old tab is also calling your API with old request shapes. Keep API changes backward compatible across at least one release, so old clients keep working until they reload.

What an interviewer is testing: that you think about two versions running at once — the normal state of every deployed web app for minutes or hours after a release.

Case 7 — "CORS Error Only in Production"

Symptom. The browser console shows Access to fetch at 'https://api.example.com/v1/orders' from origin 'https://www.example.com' has been blocked by CORS policy. Locally, with the frontend on localhost:3000 and the API on localhost:4000, everything works.

First five minutes. Do not touch CORS settings yet. Open the failing request in the Network panel (Chapter 5) and answer three questions: was there a preflight OPTIONS request, and what status did it get? What status did the real request get? Does the response carry an Access-Control-Allow-Origin header, and what value? Then reproduce the preflight with curl (Chapter 6) so the browser is out of the picture.

Hypotheses.

Why it works locally. In development, the API's CORS config often allows any origin, or a dev proxy makes the frontend and API the same origin, so CORS never applies. Production is the first place the real policy runs.

Fix. Whichever hypothesis was confirmed: add the exact production origins (including www, and a pattern for preview URLs if needed); handle OPTIONS before auth; add CORS headers to error responses too; return the exact origin with Allow-Credentials: true instead of *; add Vary: Origin when the allowed origin depends on the request.

What an interviewer is testing: that you know CORS is enforced by the browser on responses, that a CORS error can hide a real server error, and that you reproduce the preflight before changing configuration.

The Pattern Behind Every Case

Every case in this chapter was solved the same way: name the difference between the working and failing environments, then reproduce the failing environment on purpose.

The Causal Chains

The Rule You Keep Forever

"It works on my machine" means "my machine is different." Find the difference — configuration, build, runtime, time zone, topology, data or version — and make your machine fail the same way before you change any code.

Vocabulary Map

Practice Problems

Problem 1 — List the differences. A PDF export works locally but produces a blank file in production. Write down at least six differences between your laptop and the production container that could explain it, and the cheapest check for each.

Problem 2 — Build or runtime? For each value, say whether it should be build-time or runtime configuration, and why: (a) the public analytics key; (b) the database password; (c) the API base URL a browser calls; (d) a feature flag you want to flip without redeploying.

Problem 3 — The date bug. A booking page shows "Fri 10 Oct" for an Indian user and "Thu 9 Oct" for a Brazilian user, for the same booking. The API returns "2026-10-10". Write the one-line explanation, the two-minute reproduction, and the fix.

Problem 4 — Scaling out. A service works on one instance. List three kinds of state (other than sessions) that commonly live in process memory and break when you run three instances, and where each should move.

Problem 5 — Two versions at once. You are about to rename a field in an API response from userName to displayName. Old browser tabs will keep calling the API for hours after the deploy. Describe a rollout that never breaks either old or new clients.

What's Coming Next

Many of these cases had a cache somewhere in the story: a bundle cached with the old value, an old page cached in a tab. Chapter 12 is entirely about caches — the single most common source of "it's fixed but users still see the bug," of data shown to the wrong user, and of the outage that starts the moment a cache is emptied.