known errors & workarounds
Free templates for Jira Service ManagementTry the demo

Known error templates for Jira Service Management

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.

Known error template

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.

FieldWhat to writeExample
TitleThe problem in the words users use, with the error code if there is oneEmail bounces with 550 5.1.1 (recipient not found)
Error codesEvery exact code or message users see, separated by commas550 5.1.1, RESOLVER.ADR.RecipNotFound
ServiceThe service or app that is affectedEmail
Also described asOther ways users describe the same problem, one per line
  • email bounced
  • undeliverable message
  • delivery failed
Not this one ifSimilar signs that need a different fix550 5.7.1 means the receiving server refused the sender, not a wrong address
CauseWhat causes it, if knownThe recipient address does not exist on the receiving server
WorkaroundNumbered steps an agent can follow alone
  1. Check the address for typos.
  2. Remove the wrong address from the Outlook suggestions list.
  3. Send the email again.
Permanent fixLink to the problem or change that removes the causeNone needed, the address was mistyped
StateDraft, Published or RetiredPublished
OwnerThe person or team responsibleMessaging team
Review byDate to check that it is still correct2027-05-31
Linked incidentsIncidents solved with itINC-1042, INC-1077

Seven rules for known errors that agents can find

Agents find a known error only when it uses the user's words and the exact error code.

  1. Write the title the way users describe the problem, not the way IT names the cause.
  2. Copy error codes exactly, with prefixes such as 0x or AADSTS.
  3. Write one known error per cause. When two causes show the same message, write two and fill in Not this one if.
  4. Add at least three Also described as lines taken from real incidents.
  5. Write the workaround so a new agent can follow it alone, and test it once before you publish it.
  6. Give every known error an owner and a review date. When the cause is fixed, set it to Retired instead of deleting it.
  7. Link each incident you solve with it. The counts show which problems to fix for good first.

Titles that get found

Hard to findEasy to find
Mail issueEmail bounces with 550 5.1.1 (recipient not found)
Authentication failureOutlook keeps asking for the password
DNS misconfigurationWebsite does not load: DNS_PROBE_FINISHED_NXDOMAIN

Post-incident review template

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.

SectionWhat to write
SummaryWhat happened, in 2 or 3 sentences
ImpactWho was affected, how many users, for how long, which services
Timeline (UTC)When it started, was detected, acknowledged, mitigated and resolved
DetectionHow you found out, and how you could find out sooner
Root causeThe chain of causes, for example from asking why five times
What went wellSteps that limited the damage
What went badlySteps that slowed the fix
Known errorsKnown errors created or updated, with links
Follow-upDate to check that every action item is done

Action items

Give each action one owner and a due date, and create a Jira work item for it.

ActionOwnerDue dateWork item
Add an alert 30 days before a certificate expiresPlatform team2027-01-15OPS-214
Write a known error for the expired certificate warningService desk2027-01-08OPS-215

Problem record template

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.

FieldWhat to writeExample
Problem statementWhat keeps happening, where and since whenInternal sites show certificate errors when a certificate expires, since March 2026
Linked incidentsHow many incidents so far, with their keys14 incidents, including INC-0981 and INC-1013
WorkaroundLink to the known error agents use until the fixKE-024, renew the certificate by hand
Root causeWhat causes it, once foundCertificates are renewed by hand and nobody is alerted before they expire
Permanent fixThe change that removes the cause, with its linkAutomatic renewal and an alert 30 days before expiry, CHG-311
StatusUnder investigation, Known error, Fix in progress or ResolvedFix in progress
OwnerThe person or team responsiblePlatform team
Next reviewDate of the next check on progress2027-01-20

Error code catalog

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.

CodeWhere it appearsWhat it means
AADSTS50053Microsoft Entra sign-inThe account is locked after too many failed sign-ins, or the sign-in came from an IP address with malicious activity
AADSTS50055Microsoft Entra sign-inThe password has expired
AADSTS50126Microsoft Entra sign-inWrong user name or password
550 5.1.1Email bounce messageThe recipient mailbox does not exist
550 5.7.1Email bounce messageThe sender is not allowed to send to that recipient
18456Microsoft SQL ServerLogin failed, for example a wrong password, an expired password or the wrong login mode
ORA-12541Oracle Database clientNo 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.

Use your known errors inside Jira

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.

Try the demo in your browser

Get the templates as a PDF

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