Editing error messages: what happened, why, and what to do next

When I edit documentation, the error messages are often the part nobody asked me to look at. They live in the code, not in the docs folder, so they slip past review. Yet they are probably read more carefully than any page I edit, because the person reading one is stuck and wants to get unstuck.

Over time I've ended up with a simple test for any error message. It should answer three questions, roughly in this order:

1. What happened?
2. Why did it happen, if we know?
3. What can the reader do now?

Most weak messages answer only the first one, and some don't even manage that.

A before and after

Here's the kind of message I see a lot:

Error: invalid input

Invalid how? Which input? The reader now has to guess, search, or read the source. A rewrite using the three questions:

Couldn't save the project: the name "my project!" contains a character
that isn't allowed. Use only letters, numbers, hyphens and underscores,
for example "my-project".

It's longer, but every part does a job. The first clause says what failed. The middle names the actual cause and repeats the value the reader typed, so they can see the problem instead of hunting for it. The last part gives a rule and an example they can copy.

Say what failed in the reader's terms

Messages written from inside the code tend to describe the code. "NullReferenceException in ProjectService" is useful in a log, but the reader didn't do anything to a ProjectService. They clicked Save. So the message should start from the action they took: "Couldn't save the project".

If you need the technical detail for debugging, keep it, but put it after the human part or in a "details" section. Nobody should have to read a stack trace to find out their file is too big.

Don't blame, don't joke

"You entered an invalid date" and "That date isn't in a format we recognise" carry the same information. The second one doesn't point a finger. It's a small edit, and it makes a difference to someone who is already frustrated.

I'm also wary of jokes and cute phrasing in errors. "Oops, something went sideways!" might be charming the first time. The fifth time, when you've lost your work, it's grating. Plain and calm reads better under stress.

Make the next step concrete

"Please try again" is only good advice if trying again actually helps. If the fix is to change something, say what and how. If the reader can't fix it, say who can or where to look. A few patterns I reach for:

• Give the allowed format with an example: "Use YYYY-MM-DD, for example 2026-03-14."
• Name the setting or file: "Check the timeout value in settings.json."
• Point to a specific docs page, not the docs home page.

A small code example

Even in a short script you can make an error helpful. Compare a bare failure with this:

from pathlib import Path


def load_config(path):
    config_file = Path(path)
    if not config_file.exists():
        raise FileNotFoundError(
            f"Couldn't find the config file at {config_file.resolve()}. "
            "Create it by copying config.example.toml "
            "into the same folder."
        )
    return config_file.read_text(encoding="utf-8")


load_config("config.toml")

Run it without a config.toml and the last line of the traceback reads:

FileNotFoundError: Couldn't find the config file at /home/you/app/config.toml. Create it by copying config.example.toml into the same folder.

Printing the full resolved path is the detail I like most here. A surprising number of "file not found" problems turn out to be "the script was looking in a different folder than I thought", and the absolute path makes that obvious in one glance.

Collect them in one place

The most useful editing trick I know for error messages is to stop reading them one at a time. If a project keeps its messages in a single file, or you can pull them out with a quick search, read them all together in a list. Inconsistencies jump out right away: "Couldn't" in one place and "Unable to" in another, "folder" next to "directory", some messages ending with a full stop and some without. Pick one of each and apply it everywhere.

Then do one last check: trigger a few of the errors yourself and read them in context, on the screen where they actually appear. A message that reads fine in a list can be cut off in a narrow dialog, or show up somewhere the reader won't notice it. That's still part of the edit.