Write known errors the support team will use

A known error is only useful if the person on the next call can follow it. A precise cause that stays in an engineer’s notes does not shorten the next incident.

Why it matters

Repeat incidents are usually restored by the service desk or a second-line team, not by the person who found the cause. If the workaround is missing, vague, or written for a specialist, those teams start from scratch.

I keep known errors so the service stays usable while a lasting fix is still going through change. The record has to be something an analyst can open at the start of the day and act on, without calling the problem owner first.

A known error is a later state of a problem, not a label for every hard ticket. You need a documented cause, or a clear current understanding of it, and a workaround other people can use. Until those exist, keep the work on the problem record.

What to put in the record

Write for the person who will search for it under pressure.

Start with symptoms in the user’s words, and the pattern that confirms a match. Time of day, the error text on screen, and what a retry does are more useful than a component diagram. Link the incidents that belong to this problem so the next analyst can see it is the same failure, not a new one.

State the cause in one plain paragraph, specific enough to drive a change. “SSO issues” is not a cause. “The portal’s sign-in callback pool fills up on weekday mornings, so sign-in times out while the identity provider is healthy” is.

Write the workaround as steps, including the actions to avoid. If the right first step is a single retry after two minutes, say so. If resetting the corporate password makes the next incident worse, say that too. Split the steps by who carries them out: the service desk, operations, and anyone who updates the status page.

Temporary steps need a limit. Restarting a pool of web workers may clear a morning spike. Say when that is allowed, and say that the failure will return until the permanent fix is in place. A workaround with no boundary becomes the way the service is run.

Name the change that removes the cause, and how you will know the known error can close. That check might be a load test of the failed path, then two weeks of morning incident counts. A record with no exit goes stale and stops being trusted.

What good looks like

The service desk resolves the next matching incident from the known error, without a bridge call to the problem owner.

Search terms match the words users and analysts type, such as “sign-in failed” or “endless redirect”.

The workaround is safe. It restores service or reduces impact without creating a second incident. Harmful first actions are written down, not left to habit.

The known error stays visible until the change is in and you have checked that the pattern has stopped. Then close it. Leave a short note so the history can still be found if a different failure appears later.

Common mistakes

Publishing a record only a senior engineer can interpret. If the desk cannot follow the steps, it is not ready.

Burying the workaround under the investigation timeline. Put the steps where they will be seen. Keep the analysis for the people who need the cause.

Leaving the obvious wrong action unstated. Teams will reset passwords, fail over, or restart the wrong tier unless the record tells them not to.

Treating the known error as the fix. It buys time. The correction still needs an owner, a change, and a check that the repeats have stopped. Closing the problem because the workaround “works well enough” is how a temporary step becomes the design.

Takeaway

Write the known error for the next person who has to restore service. Give them the symptoms, the cause, and the steps, in their language. Point to the change that removes the cause, and close the record when that change has done the job.