What to do when something breaks

Something will break. It breaks for everyone. The people who look like they never have problems are just the people who learned to read the error message instead of panicking at it.

This lesson covers the three things that break most often for first-time deployers, and how to find the message that tells you what is wrong.

Step zero: read the actual error

Before you change anything, find the error message. It will be in the deploy log or the runtime log (your host has both). Read it. Look for:

• A line that starts with Error: or error.
• A file name and a line number.
• The first message, not the last. Errors cause more errors, and the first one is usually the real problem.

If the message mentions a file and line, open that file and look at that line. You would be surprised how often the answer is right there.

fly logs

fly status

The three things that break most often

1. A missing environment variable

The error usually looks like ReferenceError: OPENAI_API_KEY is not defined or Cannot read property of undefined.

Cause: your app needs a secret that is set on your laptop (in .env) but not on your host.

Fix: go back to Lesson 3. Set the missing variable on your host. Redeploy.

2. A build command that works locally but not on the host

The error usually looks like Module not found or command not found: next.

Cause: a dependency installed on your laptop is missing from package.json (or the requirements.txt / Gemfile / whatever your language uses). Your host installs only what is listed there.

Fix: on your laptop, run npm install <the missing package> (or the equivalent for your language). This adds it to package.json. Commit and push. Your host will rebuild and this time find it.

3. A typo in an environment variable name

The error is subtle: no crash, just broken behaviour. A page shows empty data. A payment does not go through.

Cause: your code reads OPENAI_API_KEY but your host has OPEN_AI_API_KEY or OPENAI_KEY. The names must match exactly, including underscores and capitalisation.

Fix: open the environment variables page for your host. Check every name matches what your code expects. Rename or re-add as needed. Redeploy.

When you cannot figure it out

Copy the full error message, paste it into Cursor or Claude Code, and ask what it means. Include these three things in your message:

1. What you were trying to do.
2. What you expected to happen.
3. The full error message, copied exactly - with one caveat.

Before you paste, scan the error for anything sensitive. Error messages sometimes include parts of a database connection string, an API key, a token, or a file path that could reveal information about your setup. If you see anything that looks like a password, a long random string, or a URL with credentials in it (something like postgres://user:password@host/db), replace it with REDACTED before pasting. Never paste raw secrets into any AI tool, even a trusted one.

If the error itself is telling you a token is invalid or expired, rotate that token on the service that issued it - assume it is compromised.

This works better than you would expect. Most deployment errors are very common and have well-known fixes.