"Works on My Machine"

Maya finishes a change to Pageturn. On her laptop it runs perfectly — the page loads, the new feature works, every test passes. She hands it off, Sam puts the very same code on the server that real readers use, and it breaks. Nothing in the code changed between her laptop and his server. Something around the code did.

This is so common it has a name, half-joke and half-complaint: "works on my machine." It is one of the oldest and most maddening problems in software, and an entire family of tools — the subject of this chapter — exists to make it stop happening. Before we get to the fix, it's worth seeing clearly what actually goes wrong.

The Symptom: Same Code, Different Result

Start with what you can see. The exact same code — copied byte for byte, not retyped or edited — produces one result on one computer and a different result on another. It runs here and crashes there, or behaves slightly differently in a way that quietly causes trouble.

That is genuinely strange the first time you meet it. We expect a program to be like a recipe: follow the same steps and you get the same dish. So if the code didn't change, why did the outcome? The answer is that the code was never the whole story.

The Cause: The Environment Differs

Code never runs by itself. It runs on top of a pile of other things: the specific version of the programming language it's written in, the extra tools and libraries it calls on, and dozens of settings the computer carries. All of that together is the program's environment — the surroundings the code depends on to run. From here on we'll call it the environment.

"Works on my machine" happens when two environments don't match. Maya's laptop has version 3.12 of a tool; Sam's server has 3.9. Her laptop has a setting switched on that his doesn't. A small piece her code quietly relies on was installed on her machine long ago and never on his. The code is the same. The ground it stands on is different, so it falls differently.

Why It Happens So Often

Here's the uncomfortable part: every computer is a little different from every other one. They've had different things installed, in a different order, at different times, with different versions and settings accumulating for years. No two machines are truly identical, even when they look the same.

Think of a recipe that comes out great in your kitchen and flops in a friend's. Same instructions, but a hotter oven, a different brand of flour, a missing spice — the recipe alone was never enough, because it assumed your kitchen. Code assumes its machine in exactly the same way. That's why the problem is the rule, not the exception, and why blaming the developer misses the point.

The Goal: Carry the Environment Along

Once you see that the trouble is the mismatch between environments, the fix almost suggests itself. If the problem is that the surroundings change from machine to machine, then make the app stop depending on the machine it lands on. Bundle the environment up with the app, so wherever it goes, its surroundings go too.

That bundle is what the next topic is about — the container. It's the idea that finally lets Maya's laptop and Sam's server agree. When you later take this hands-on in the Docker Deep Dive course, this exact frustration is the problem you'll be solving; everything Docker does is in service of killing "works on my machine." Connects to: the next topic (what a container is) and the Docker Deep Dive.