A free template pack for IT teams that fix the same problems again and again. Start with the 10 incidents your team solves most often and write one known error for each.
Keep the templates wherever your team already works: a Confluence page, a Jira work type with these fields, or a shared sheet. The fields matter more than the tool.
Want them as a PDF? Get the 6-page PDF by email.
A known error is a problem with a known cause or a tested workaround, written so the next agent can fix it in minutes.
The example column shows a filled known error for a common email bounce.
| Field | What to write | Example |
|---|---|---|
| Title | The problem in the words users use, with the error code if there is one | Email bounces with 550 5.1.1 (recipient not found) |
| Error codes | Every exact code or message users see, separated by commas | 550 5.1.1, RESOLVER.ADR.RecipNotFound |
| Service | The service or app that is affected | |
| Also described as | Other ways users describe the same problem, one per line |
|
| Not this one if | Similar signs that need a different fix | 550 5.7.1 means the receiving server refused the sender, not a wrong address |
| Cause | What causes it, if known | The recipient address does not exist on the receiving server |
| Workaround | Numbered steps an agent can follow alone |
|
| Permanent fix | Link to the problem or change that removes the cause | None needed, the address was mistyped |
| State | Draft, Published or Retired | Published |
| Owner | The person or team responsible | Messaging team |
| Review by | Date to check that it is still correct | 2027-05-31 |
| Linked incidents | Incidents solved with it | INC-1042, INC-1077 |
Agents find a known error only when it uses the user's words and the exact error code.
0x or AADSTS.| Hard to find | Easy to find |
|---|---|
| Mail issue | Email bounces with 550 5.1.1 (recipient not found) |
| Authentication failure | Outlook keeps asking for the password |
| DNS misconfiguration | Website does not load: DNS_PROBE_FINISHED_NXDOMAIN |
Hold a review within 5 working days of every major incident, for example one that hit many users or stopped a service for more than an hour.
Describe what the systems and steps allowed, never who is to blame, so people share what really happened.
| Section | What to write |
|---|---|
| Summary | What happened, in 2 or 3 sentences |
| Impact | Who was affected, how many users, for how long, which services |
| Timeline (UTC) | When it started, was detected, acknowledged, mitigated and resolved |
| Detection | How you found out, and how you could find out sooner |
| Root cause | The chain of causes, for example from asking why five times |
| What went well | Steps that limited the damage |
| What went badly | Steps that slowed the fix |
| Known errors | Known errors created or updated, with links |
| Follow-up | Date to check that every action item is done |
Give each action one owner and a due date, and create a Jira work item for it.
| Action | Owner | Due date | Work item |
|---|---|---|---|
| Add an alert 30 days before a certificate expires | Platform team | 2027-01-15 | OPS-214 |
| Write a known error for the expired certificate warning | Service desk | 2027-01-08 | OPS-215 |
Open a problem when the same known error keeps coming back.
The problem tracks the work to remove the cause, while the known error keeps agents fixing incidents in the meantime. The example follows the certificate incident from the review above.
| Field | What to write | Example |
|---|---|---|
| Problem statement | What keeps happening, where and since when | Internal sites show certificate errors when a certificate expires, since March 2026 |
| Linked incidents | How many incidents so far, with their keys | 14 incidents, including INC-0981 and INC-1013 |
| Workaround | Link to the known error agents use until the fix | KE-024, renew the certificate by hand |
| Root cause | What causes it, once found | Certificates are renewed by hand and nobody is alerted before they expire |
| Permanent fix | The change that removes the cause, with its link | Automatic renewal and an alert 30 days before expiry, CHG-311 |
| Status | Under investigation, Known error, Fix in progress or Resolved | Fix in progress |
| Owner | The person or team responsible | Platform team |
| Next review | Date of the next check on progress | 2027-01-20 |
Keep one list of the codes your users report, so every agent reads a code the same way.
Start with these seven and add a column that links each code to your own known error.
| Code | Where it appears | What it means |
|---|---|---|
AADSTS50053 | Microsoft Entra sign-in | The account is locked after too many failed sign-ins, or the sign-in came from an IP address with malicious activity |
AADSTS50055 | Microsoft Entra sign-in | The password has expired |
AADSTS50126 | Microsoft Entra sign-in | Wrong user name or password |
550 5.1.1 | Email bounce message | The recipient mailbox does not exist |
550 5.7.1 | Email bounce message | The sender is not allowed to send to that recipient |
18456 | Microsoft SQL Server | Login failed, for example a wrong password, an expired password or the wrong login mode |
ORA-12541 | Oracle Database client | No database listener is running at that host and port |
Sources: Microsoft Entra error codes, RFC 3463 mail status codes, SQL Server error 18456, ORA-12541.
Known Errors & Workarounds is an app for Jira Service Management that brings these templates into Jira. It is in free beta now and goes on the Atlassian Marketplace in January.
Sign up and you get the 6-page PDF right away, an invite to try the app during the beta, and a message when it launches.
Free. You can unsubscribe any time.
Built with Kit