Back to lab notesBuild notes
Build notes3 min read

An error message needs a next step.

Explain what failed, what is still safe, and where someone can go next. A polite apology cannot do all of that work.

“Something went wrong.”

Well, yes. The person looking at the message had probably worked that out.

Imagine a small utility for assembling a printable recipe booklet. Someone has chosen recipes, adjusted the order, and added a cover. They press the button to create a PDF. Instead of a file, they get that sentence and a cheerful little warning icon.

The message has announced trouble without explaining whether their work survived. They do not know whether to correct an input or choose another destination. Starting over might only repeat the problem.

I would spend less time making the apology charming and more time answering the question it leaves behind.

Say what you know

For this hypothetical utility, different failures deserve different messages. A recipe image could be unreadable. The chosen folder could be unavailable. The tool could have lost contact with a service before confirming whether a file was created.

Those are different places to leave someone.

If the tool knows that one image cannot be read, name the affected recipe and offer a way to replace or omit that image. Keep the rest of the booklet intact. If the destination cannot be used, let the person choose another destination without rebuilding the contents.

An uncertain outcome needs uncertain wording. “We couldn’t confirm that the PDF was created” is different from “No PDF was created.” Only use the second when the application has evidence for it. The message should not convert missing information into a definite failure just because definite language is shorter.

There is a related engineering question about safe retries. Here the question is what the person can understand before deciding what to do. A button labelled “Try again” is not much guidance if they do not know which step it repeats.

Keep the next step close

Put the explanation beside the affected part of the work when possible. An image error should lead back to that image, not to the top of a long recipe list. Keep the person’s choices visible while they make the correction.

The message can be brief without being vague: “The image for Lemon Cake couldn’t be read. Choose another image, or make the booklet without it. Your recipe text is unchanged.”

That last sentence belongs only if it is true. Reassuring copy is a claim about application behavior, not a substitute for protecting the work.

Sometimes the next step is asking for help. Provide a useful reference and a concise description of the failed operation. Do not make someone send a whole private recipe collection to explain a problem with one image. Technical details can sit behind a disclosure for someone who needs them; they do not need to be the opening line.

Read the error message on its own during a design review. Then follow the action it offers. Does it take you to a place where the problem can actually be addressed, with the work you already did still available?

A failure may remain inconvenient. The interface can at least spare someone the extra task of investigating what its apology meant.