The environment variable that cost me a day

One day, a feature worked perfectly locally and fell over in production. Same code, same database. The difference: an environment variable that existed in my .env.local and nowhere else. The code read it as undefined, took a default path I'd written for development, and quietly did the wrong thing in front of real users.

The lessons, priced in one lost day

Validate config at startup. The app should refuse to boot when something required is missing — loudly, with the variable's name in the error. Silent defaults for required config are landmines with a delay timer.

Separate required from optional, in code. Optional values can have defaults. Required ones get assertions, not fallbacks.

Document every variable where it's used. A one-line comment above each process.env read: what it is, what happens without it. Future setup-me at midnight will bless present-me.

The general shape of the bug

This is the "worked on my machine" genre, and the root cause is almost always an untested difference between environments. The fix isn't being careful — it's making the environments prove themselves. Startup validation, a config checklist in the README, and deploys that fail fast instead of failing weird.

The bug was never the missing variable. The bug was that absence was allowed to proceed.