Environments: why it works on your machine and breaks online

Engineers have a name for this moment. It works on my machine is the oldest complaint in software: the code is the same in both places, and something around the code is not.

The log shows what the error page hides

The error page is written for visitors and says almost nothing. A log is the running list of lines a program writes while it works, and every host shows it on a tab with that name. Near the moment the member hit the page, two lines show the problem:

Error: MODEL_API_KEY is not set
    at tidy (app/api/tidy/route.js:4)

The first line says the program looked for a value called MODEL_API_KEY and found none. The second says where: line 4 of app/api/tidy/route.js, the file behind the tidy page's endpoint. That value is the API key from The journey of a request.

An environment variable is a value a program reads from its surroundings when it starts, not from its own code, like a sticky note read at startup. The .env file is the locked drawer from the plan, a small text file of those values that stays on your laptop. The agent wrote MODEL_API_KEY into it when it wired the tidy page, so the page worked at home. The host has a screen for the same notes, called Environment Variables, and its row for MODEL_API_KEY stayed empty until you filled it.

The key stayed home because of a second small file. The file .gitignore is a short list of files git must never save, a do-not-pack list, and .env is on it. The host received only the files git had saved, so the code traveled and the secret stayed home.

The fix takes five minutes

To deploy is to move code from where it runs now to where users can reach it, the way a recipe moves from your kitchen to a restaurant's. Paste the value into the empty row on the host, then ask the agent to deploy again. A build is the runnable version the host makes from your files before it starts the site, and it makes a new one on every deploy. This time the build starts with the note in place, the log stays quiet, and the club's link shows a clean post.

Deploy means moving code from where it runs now to where users can reach it. The code travels; the settings around it do not, so you set them again at the destination.

What was actually different

One value existed on your laptop and not on the host, and that was enough to break a page. The setup around code holds many details like it. An environment is everything around the code, the kitchen around the recipe. The other machine is rarely broken; the two kitchens differ in a detail you have not found yet.

An environment is everything around the code: the machine, the installed tools, the settings, and the data. The same code in two environments can behave like two different products.

The three environments most teams run

You eventually meet these differences on every product, so teams give standard names to the places where code runs. The Environment Variables screen is already built around these three names: beside each value, the host asks which copies of the site may see it.

• Development is your own machine, and there breaking things is cheap and private. The site has run there since the morning you first started it.
• Preview is a private copy the host makes for each change, a dress rehearsal before anyone outside sees it. Teams once built this copy by hand and called it staging.
• Production is the real thing, the version your users touch; think of it as opening night.

A change starts on your machine because there it can fail with no audience. Next it goes to the preview copy, where the host's kitchen exposes what your laptop hid, and only then to production.

You do not build the middle zone yourself: every time the agent pushes a change to GitHub, the host makes a preview copy for free and shows you a private link. Your missing key, sent through preview first, would have failed in front of you instead of the club.

The obvious objection: this is ceremony for one person with one laptop

Gates sound like process built for companies, so shipping straight from the laptop to the live site is tempting. But you already run two of the three environments: your laptop has been development since the site first ran there, and the link you sent the club is production. The host makes the third for free with every push, so the only ceremony left is opening the preview link before anyone else sees the change. Choosing and paying for the host is a topic for Hosting, renting a computer on the internet, later in the course.

What happens when a change skips the gates

On July 19, 2024, the security company CrowdStrike sent a faulty update to software running deep inside Windows machines worldwide. About 8.5 million machines crashed, flights were grounded, and payment systems stopped. The update went to every machine at once. In its review afterward, CrowdStrike committed to sending updates to a few machines, watching, and only then widening. Watching those first machines is the subject of Monitoring, how you know it broke (and what it costs).

The cost of a bad change grows with the number of people who meet it, so a change goes to your machine, then a preview copy, then the live site.

The map, complete

You can now understand the plan an agent prints and place each part of a product on the map from Where software lives. When a site works at home and breaks online, you can read the log for the value that exists in one place and not the other.

Try it now

This drill takes about fifteen minutes. It costs nothing on the first path and a few cents of usage on the second.

No setup: Open the AI chat you already use and paste: "A site works on my laptop but fails online. The deploy log says: Error: MODEL_API_KEY is not set. What is that value, where does it live on my laptop, and where do I set it on the host?" Check the answer against the two key ideas above, the one on deploy and the one on what an environment is.

With your tools: You arrive with the idea file and a first save point in the running-club folder. In Claude Code, the AI coding tool we use in this course, type: "Deploy this project to Vercel and show me the deploy log." After a sign-in to Vercel, it prints a link ending in vercel.app. If the tidy page there shows the Application error page, type: "Read the deploy log and walk me through adding the missing environment variable on Vercel." Paste the value from .env into the empty row, deploy again, and the page works. Then ask the agent for any small change, and before you touch production, open the private preview link the host shows for that push. Codex and Cursor, two other coding tools, accept the same requests in their chat panels. If nothing is installed yet, The Setup Clinic covers the install.

Either way, finish by consolidating the idea file. It arrived with one line per chapter; give it this five-line header above those lines:

What I approved and why
Idea:     a running-club site with trails, RSVPs, and a tidy page
Approved: host Vercel; JavaScript with Next.js;
          the AI step runs on the server
Rule:     save point before every agent session
Secret:   MODEL_API_KEY, in .env on my laptop,
          in Environment Variables on Vercel
Words:    environment, deploy, log, preview, production

Later chapters add lines beneath that header.

Chapter Summary

• The site broke online because one environment variable, MODEL_API_KEY, existed in the .env file on your laptop and not on the host; the host's log named it.
• Deploy means moving code from where it runs now to where users can reach it; the code travels, the settings around it do not, so you set them again at the destination.
• The .env file stays on your laptop because .gitignore lists it as a file git must never save, and that is the right place for a secret.
• An environment is everything around the code: the machine, the installed tools, the settings, and the data. The same code in two environments can behave like two different products.
• Most teams run three environments: development on your own machine, preview as a private copy the host makes for each change, and production where your users are.
• A change moves from development to preview to production, and it moves to the next environment only after it worked in the one before; the host makes the preview copy for free on every push.
• The cost of a bad change grows with the number of people who meet it; the CrowdStrike outage of July 2024 reached 8.5 million machines at once.
• When an agent says a change is tested, ask where it ran before you trust it.
• Your artifact is the idea file, now with its header "What I approved and why" above the line from each chapter.
• Next, Frontend, what users see opens the next part with the layer of the site your members actually see.

Sources

• CrowdStrike post-incident review of the July 19, 2024 content update (last verified July 2026).
• Public news reporting on the July 19, 2024 global IT outage (last verified July 2026).
• Vercel documentation on environment variables and preview deployments (last verified July 2026).
• Netlify documentation on deploy previews (last verified July 2026).
• Git documentation on gitignore, git-scm.com (last verified July 2026).