Every internal tool fails sometimes. What decides whether the failure costs five minutes or half a day is usually not the bug itself but the message on the screen. "Error 500" or a wall of stack trace leaves an employee guessing: did my order save, should I click again, who do I call? Good error messages are cheap to write and are one of the clearest signs that a tool was built for the people using it.
One plain sentence for staff
The message the user sees should answer three questions in everyday words: what did not work, was anything lost, and is it their fault.
- Weak: "NullReferenceException at OrderService.cs:142".
- Better: "We could not save this order. Nothing was changed, and your entries are still on the screen."
Avoid blame ("Invalid input") and avoid vague reassurance ("Something went wrong"). If the cause is something the user can fix, say which field and what is expected: "The delivery date must be after today."
Tell people what to do next
A message without a next step creates a support call. Pick one of three endings and use it consistently:
- Retry. "Try again in a minute." Use it only if retrying is safe and likely to help.
- Work around. "You can enter this order on the paper form and we will add it later."
- Contact. "Contact the support desk and quote code E-4821." Name the person or channel, not "the administrator".
If the tool does not know whether the action went through, say so and tell the user how to check, for example by opening the order list. A duplicate order caused by a second click is worse than a visible error.
The technical detail goes to a log
Developers need the opposite of what staff need: exact time, user, screen, the data involved and the full technical error. Put all of this into a log or an error-tracking tool, and keep it off the screen. Two reasons: technical text confuses users, and it can expose internal names, file paths or personal data to people who should not see them.
A minimal log entry contains:
- time and the user's account,
- the screen or action,
- the technical error and where it happened,
- the incident code shown to the user.
For more on what to record in the first place, see what to log in a small internal tool so support questions answer themselves.
Give each error an incident code
A short code, such as E-4821, links the two worlds. The user reads it to the support desk, support finds the exact log entry in seconds and does not need to ask "what were you doing at around ten?". Two simple rules:
- Generate the code when the error happens, so each occurrence is unique, and show it on screen.
- Keep a second, stable error type in the log, so you can count how often the same problem occurs.
Let the user copy the code with one click. People under time pressure will not retype it correctly.
Who receives what
Decide this before launch, in one small table:
| Kind of error | Staff see | Who is notified |
|---|---|---|
| User can fix it (missing field, wrong format) | Which field and what is expected | Nobody |
| Temporary (network, busy service) | Retry message with code | Nobody, unless it repeats |
| Tool fault (bug, failed save) | Plain sentence, next step, code | Developer or the tool owner |
| Data at risk (failed import, mismatch) | Stop message and contact | Tool owner immediately |
Notifying developers about every error trains them to ignore the channel. Notify on new error types and on sudden increases, and let the rest wait for the monthly review.
A ten-minute monthly review
Once a month, the tool owner and a developer look at the log for ten minutes:
- Sort the incident types by how often they occurred.
- Pick the top three. For each one decide: fix the cause, improve the message, or leave it.
- Check one message in the real tool by reading it as a new employee would.
- Note what was changed, so the next review shows whether the count dropped.
Most tools have a small number of errors that account for most of the noise, so fixing three each month makes a visible difference within a quarter. If a problem needs a proper triage routine, bug triage for internal tools describes one.
Common mistakes
- Showing the stack trace to users. It helps nobody on the shop floor and can leak internal details.
- "Something went wrong" with no code. Support cannot find the cause and users cannot describe it.
- Messages in developer language. Write them with the people who use the tool, and test them on one of them.
- Hiding errors completely. If a save fails, the user must know. Silent failures are worse than visible ones.
- No owner. If nobody reads the log, the best messages will not improve the tool.
Summary
Write each error message for the person who sees it: one plain sentence, whether their data is safe, and what to do next. Send the technical detail to a log, link the two with a short incident code, and decide who is notified for which kind of error. Spend ten minutes a month on the most frequent codes. The result is fewer support calls, faster fixes and staff who trust the tool even on the days it fails.
Sources
- Common practice for building and supporting internal tools, offered as a practical guide. No client results or market figures are claimed in this article. Adapt the wording, the notification rules and the review period to your own tool, and check local rules on personal data in logs where they apply.
