"But it worked on my machine"

There’s a phrase every developer says at least once, usually in a small voice: “But it worked on my machine.”

I said it on a Friday afternoon, a long time ago, and I’ve never forgotten it. I’ve spent most of my career since then running servers, and I can tell you that this one sentence explains more outages than almost anything else I’ve seen.

Back then I’d just joined a small studio and was handed my first solo project for a client. Forms, a gallery, a bit of custom code. On my laptop it was gorgeous. I clicked through every page. Everything worked. I felt like I’d grown a full inch taller.

I uploaded it to the live server at 4:45 p.m. and loaded the address.

A white page. Nothing on it at all.

The blank page

No error, no message, no helpful little sad face. Just white, like the site had never been born.

I refreshed. I cleared my cache. I uploaded the files again, as if the first time had been shy. Still white.

My laptop, meanwhile, was still showing the site perfectly. So the code was fine. It had to be the server’s fault, right? I actually typed a complaint to the host’s support before a more experienced colleague leaned over and said, kindly, “Have you looked at the error log?”

I had not. I hadn’t known there was one.

What the log said

The log told me everything, in about four lines. There were three separate problems:

1. A different PHP version. My laptop ran a newer one than the live server. I’d used a feature the older version didn’t understand, so it gave up and showed a blank page.
2. A file-name case mismatch. I’d named a file with a capital letter but referred to it with a lowercase one. My laptop didn’t care; the live server did. On most live servers, Logo.png and logo.png are different files.
3. A missing extension. My code relied on a small add-on that was installed on my machine but not switched on live.

None of these were dramatic. Every one was invisible until the code met a different environment. That’s the part that took me years to really absorb. A server isn’t a bigger, faster version of your laptop. It’s a different place, with its own rules, and your code has to be introduced to it properly.

There was a small silver lining. My colleague didn’t take the keyboard and fix it for me. She sat beside me and asked me to read each line of the log out loud, and then to say what I thought it meant. It was slow and slightly embarrassing, and it taught me more in twenty minutes than a week of tutorials. When I train junior people now, I do exactly the same thing. The goal isn’t a fixed page. It’s someone who knows where to look the next time the page goes white.

How I work now

I fixed all three that evening and stayed until the page loaded, feeling both mortified and weirdly educated. But the real change was in habits, and they’re the same habits I put in place for every client’s servers today.

First, I find out which PHP version and extensions the live server uses, and I match them in the development setup. Second, I ask for a staging copy, a private duplicate of the live setup, so I can test there before touching the real thing. Third, no Friday afternoon deploys. If something goes wrong at 4:45 p.m. on a Friday, you spend your weekend on it, and so does the client. And fourth, before I panic, I open the logs.

That last one sounds obvious. It isn’t, when you’re staring at a white page with your stomach sinking. The instinct is to change something, anything, to feel like you’re doing work. The better instinct is to read what the server is already trying to tell you. In more than twenty years, the log has been right far more often than my theories have.

A few things I’d tell you

• Find out your live environment’s details: PHP version, extensions, settings.
• Match them locally, as closely as you can.
• Mind your file names. Capital letters matter on most live servers.
• Use a staging site and test there first.
• Read the error logs before guessing. They usually just tell you.
• Avoid deploying right before the weekend.

Test where your visitors are, not only where you code. Those three problems cost me one evening and a bruised ego. Left alone, they’d have cost the client a launch day. And if you ever hear yourself say the famous sentence, take it as a cue to go and look at the log.