Writing Error Messages That Help People Recover

Replace vague failures with messages that explain the problem and next step.

“Something went wrong” leaves visitors guessing. A useful message identifies the issue, points to the affected input, and offers a safe next action without blaming the user.

Name the problem

If a file type is unsupported, state accepted types. Keep internal stack traces and server paths out of public messages, while logging diagnostic details securely.

Offer the right action

Suggest correcting an input, choosing another file, or trying later. Do not offer a retry if repeating the action could create duplicate transactions.

Test failure states

Try missing values, invalid formats, and oversized files. Preserve valid work and make messages accessible to keyboard and assistive-technology users.

Before relying on the result, test a small example, keep an original copy when a file or value is transformed, and check the output in the application where you plan to use it. Browse the tools directory for a utility that matches your task, and use the other practical guides for related checks.

Editorial note: This guide provides general educational information. Follow the requirements of the software, service, or organization involved when a task has specific rules.