Error Message Design: Share the Recovery When You Build in Public

When you share error message design while building in public, show the failure, the explanation and the recovery step together. A screenshot of improved wording can invite useful criticism, but a small walkthrough lets peers judge whether the person using the product can actually continue the task.

Choose one recoverable failure and use invented sample data. Explain the intended task, what caused the failure and what the product preserves. Then ask a focused question about the next action. Keep feedback on the wording separate from evidence that someone successfully recovered in the working interface.

Pick a failure the person can do something about

Consider a fictional SaaS tool that imports a repair shop's parts list from a CSV file. The sample file has a column named Item code, but one row has no code. The importer rejects the file. That gives the developer a specific situation to show without exposing a customer's real inventory or using an actual failed upload as public material.

Start the post by explaining the task: add the sample parts to the product. Show the relevant sample column and the current response. A message such as “Import failed” gives the reviewer little to assess. They need to know whether the problem concerns the file format, a missing value or a failure inside the service.

The GOV.UK Design System's error-message guidance distinguishes validation problems from service problems the user cannot fix. That distinction matters in this example. A missing item code may be correctable in the file. An unavailable import service needs a different explanation and next step, rather than an instruction to repair valid data.

Write the proposed message against a known condition

For the fictional missing-code case, proposed wording could identify the sample row and column, explain that no items were imported and tell the person to add the missing code before uploading again. Each part needs to match the actual import behavior. If some rows were imported, saying none were added would create a new error.

Do not promise that retrying is safe without checking what the application does. A partial import may require the person to review existing records first. The message should communicate the state the system knows. If it cannot determine whether anything was saved, that uncertainty belongs in the recovery flow rather than being hidden by reassuring copy.

Use row numbers only when the interface and downloadable file use a consistent numbering convention. Does the header count as a row? Can blank lines change the reported number? In the public example, state the convention or point directly to the relevant sample value. Precision that sends someone to the wrong place is worse than a less compact explanation.

Keep the attempt visible during recovery

Show what happens after the error appears. Does the chosen file remain identified? Can the person inspect the problem before replacing it? Does a second upload clearly replace the first attempt? A message can sound clear in isolation while the surrounding interface makes it hard to understand which state is current.

GOV.UK's guidance also recommends preserving entered answers when validation errors appear. Applied to this fictional import, the review question is what useful context the product can retain. Retaining a file name or a summary of the attempt is different from storing an uploaded document indefinitely. Describe the behavior you actually implement.

Do not collect or publish extra sample information just to make the demonstration feel realistic. A few invented parts can expose the interaction. Real supplier names, purchase costs and customer details are unnecessary for a review of the missing-code message. If the sample cannot explain the failure without private records, redesign the example before sharing it.

Capture the whole recovery path

Prepare a short sequence with a clear beginning and end. Start from the import screen, choose the deliberately incomplete sample, show the error and then use the corrected sample. Finish at the state that confirms what was added. Keep the changed input visible enough that a reviewer can understand what caused the later success.

Label the demonstration as a staged sample. It shows that this path behaved as described under these conditions. It does not establish that new users understand the message, that every invalid file is handled correctly or that the importer is safe for production workloads. Those are separate questions with separate evidence needs.

If the sequence is only a prototype, say which parts are simulated. A clickable mockup that displays a success card has not completed an import. You can still ask peers to critique the wording and information order. Just avoid presenting a simulated completion as a working product result in the post, cover or caption.

Ask peers to explain the next action

Instead of asking whether the new message looks better, ask what they would do next after reading it. A useful response might reveal that the row reference is unclear, that the person expects to edit inside the application or that they are unsure whether anything has already been saved. Those are concrete gaps to investigate.

Ask respondents which part of the sequence led them to that interpretation. That keeps the discussion attached to the artifact. A suggestion to add a button may be valuable, but you still need to understand the confusion it would address. Otherwise, a small copy review can become a collection of unrelated feature requests.

For a community post, include the role you most want to hear from. Developers can identify inconsistent system states; someone who regularly imports parts lists may question the workflow itself. Both can help, but their observations answer different questions. Record that context instead of combining every reaction into a single verdict.

Separate a copy review from a recovery test

A person reading a screenshot can tell you how they interpret it. A person trying the task can show what they actually do. If you move from public discussion to a guided session, use the same defined sample and let the participant respond before explaining the intended path. Record any help you provide.

Suppose, in a hypothetical session, someone corrects the missing value but cannot find how to replace the file. That would direct attention to the upload interaction. It would not prove the revised wording is useless. Write the observation narrowly and revise the part of the flow that prevented the task from continuing.

Likewise, successful recovery in one sample session is evidence about that attempt, not a universal usability claim. Keep the conditions and remaining questions beside the result when you share the follow-up. The useful public update explains which uncertainty changed and which still needs work.

Share what the review changed

The follow-up should show the specific revision and its reason. Perhaps the fictional developer adds a clear replacement-file action and makes the import state explicit. Show that change with the same sample so readers can compare the flow. Avoid turning a few helpful comments into a claim that the community validated the entire product.

Buildside's public description connects founder progress with specific peer contributions; I build Buildside. This kind of bounded recovery review gives that contribution a concrete object. Someone can inspect one failure path and challenge its explanation without needing to become a customer or review the entire application.

Before publishing your next build update, choose one error your product can explain more honestly. Prepare the smallest sample that reveals it, show the recovery and ask what the reader would do next. Then use the response to improve the real task. The valuable progress is the clearer route back to useful work, with evidence that says exactly how far you have checked it.

Hey I'm Uriel Bitton. I write about building in public strategies and growing startups.

Subscribe for more stories on growing your audience by building in public.

Join us on Buildside: the social network for founders building in public.

Sources

GOV.UK Design System: error messages

About Buildside and its founder