Your local dev environment is a comfortable fiction. It runs your code, it passes your tests, it makes you feel like things are working. Then you deploy to production and something breaks that you've never seen before. This is not bad luck. This is the nature of the thing.
The gap between local and production is one of those problems that's been "solved" many times — Docker, Vagrant, Nix, reproducible builds — and yet it persists. Because the gap isn't really about the tools. It's about the assumptions baked into every environment that nobody writes down.
Here's a partial list of things your local environment lies to you about: file system case sensitivity (macOS is case-insensitive by default; Linux is not), timezone (your machine has one; your server has another), available memory (your laptop has 32GB; your container has 512MB), network latency (localhost is fast; the real world is not), and the specific version of every dependency that happens to be installed on your machine right now.
The case sensitivity one gets people constantly. You write import MyComponent from './mycomponent' and it works locally because macOS doesn't care. You push to a Linux server and it fails because Linux does care. The error message is confusing. The fix is obvious in retrospect. The time lost is real.
I've been writing about this kind of thing on terminal-first workflows — the idea that understanding your environment at a low level is not optional if you want to ship reliable software. You don't have to be a sysadmin. But you do have to know what your code is actually running on.
The timezone problem is subtler. Your local machine is set to your timezone. Your server is probably UTC. If you're doing any date math — and you probably are, even if you don't think of it that way — you will eventually hit a bug that only happens at certain times of day in certain timezones. These bugs are extremely annoying to reproduce and debug.
Memory is the one that surprises people most. You write code that works fine on your laptop with 32GB of RAM. You deploy it to a container with 512MB. It crashes. Not because your code is wrong, exactly, but because it was written for an environment that doesn't exist in production. The fix is usually not hard. Finding the fix requires knowing the problem exists.
The solution isn't to make your local environment perfectly match production — that's a losing battle. The solution is to know the differences and account for them. Run your tests in a container that matches production. Use environment variables for anything that differs between environments. Be suspicious of anything that "just works" locally without you understanding why.
There's a related problem I've been thinking about over at building for the web — the way web development specifically has accumulated layers of abstraction that make it easy to build things without understanding what's happening underneath. That's mostly fine until it isn't.
The dev environment lies to you because it's optimized for your comfort, not for accuracy. That's a reasonable tradeoff most of the time. Just don't forget it's a tradeoff.
The most reliable thing I've found: before you ship anything significant, ask yourself what assumptions your code is making about the environment it's running in. Write them down. Check whether production satisfies them. This takes ten minutes and has saved me hours of debugging more times than I can count.
Your local environment is a tool. Like any tool, it's useful when you understand its limitations. The pattern recognition in code that separates good engineers from great ones is often just this: knowing what you don't know about the environment your code runs in.
The lie isn't malicious. It's just comfortable. Comfort is fine. Just don't mistake it for truth.