Known Errors and Workarounds: Write the Fix Down Once

Wednesday, 11:40, at Ashgrove Housing. Owen is in his second week on the desk and has just picked up a ticket from a repairs officer: "Photos won't upload from the repairs app on the tablet, keeps saying 'sync failed'." He reads the app's documentation, checks the tablet's storage, checks the Wi-Fi, and reinstalls the app. At 12:30 he walks over to Farah, who has been on the desk for four years. "Oh, that one," Farah says. "Clear the app cache and sign in again. Takes a minute. Happens all the time." It does happen all the time; there are twenty-two tickets about it. Owen has just spent fifty minutes rediscovering something that was known, by one person, and written down nowhere.

A known error is a problem the desk understands well enough to recognise on sight and to get round reliably, while the permanent fix is still waiting. A workaround is that reliable way round: the fastest tested way to restore the symptom, written as steps anyone on the desk can follow. Between "we know what this is" and "we have fixed it for good" there is usually a gap of weeks or months. The known-error record exists so that every repeat inside that gap costs a minute instead of fifty. This article is part of our Problem Management series, and it is about that gap.

It starts with what a known error is and why it is a status rather than a thing. Next comes what makes a workaround worth writing down and publishing it where the technicians will find it. Then comes linking every new ticket to the known error, so the count keeps rising. After that: what to tell the requester, and keeping known errors alive and retiring them when the fix goes in. It ends with a short war story and the known-error record to copy.

A Known Error Is a Status, Not a Separate Thing

A known error is what a problem becomes when two things are true. The desk can recognise the symptom reliably, and there is a workaround that has been tested and written down. It is a status the problem record reaches, between "investigating" and "fix scheduled", and in the formal frameworks it also requires the root cause to be understood. On a small desk, be practical about that last part. If the cause is proved, the record says so. The cause may be only probable, or unknown. If the symptom is unmistakable and the workaround works every time, that is still a known error for every purpose that matters on a Wednesday at 11:40. The requirement is that the next technician recognises it and gets round it, not that the desk has finished thinking.

The status matters because of how long it lasts. A problem may be investigated in an afternoon. But the permanent fix waits for a change window, a budget, a supplier, a quiet week, or a decision from someone who is on leave. That wait is measured in months. The tablets at Ashgrove needed an app update from the supplier that was promised for "the next release". In the meantime there were twenty-two tickets, and there would be forty more. Most of a problem's life is spent as a known error. The record for that stage is the one that saves the most hours, which is why it gets its own article.

The record is not a fix and must not be mistaken for one. A known error with a good workaround is comfortable, and comfort is how permanent fixes get forgotten. The tickets keep arriving, each one is closed in a minute, and the problem list shows "known error, workaround published" for a year. The record carries the running count of linked tickets for exactly this reason. Forty tickets a minute each is still forty interruptions, forty requesters, and forty times someone in the field could not upload a photo. The workaround buys time for the fix, and the count is the reminder that the time is being spent.

What Makes a Workaround Worth Writing Down

A workaround is a set of steps, tested, that restores the symptom every time, and the word "every" is the test. "Try clearing the cache" is a suggestion. "Clear the app cache, sign out, sign in; the sync completes within a minute; if it does not, the tablet is on the old app version and needs the update" is a workaround. It says what to do, in order, how to tell it worked, and what it means if it did not. It also says who can do it: a technician with a remote session, the requester following three steps, or only someone standing at the device. A workaround the requester can follow is worth three times one that needs a technician, because it removes the wait as well as the work.

Write the recognition test before the steps. The first thing a technician needs is to know that this ticket is the known error and not something that merely resembles it. So the record opens with how to tell. It gives the exact wording on the screen, the device or site it affects, what the requester was doing, and one quick check that confirms it. "Sync failed" on a tablet after taking photos, where the tablet shows a storage figure below ten percent, is the known error. "Sync failed" on a tablet with plenty of storage is something else and should not get the workaround. Without the test, the workaround gets applied to everything with similar words, and a different problem hides behind the known one for months.

Say what the workaround does not do. It does not fix the cause; the photos will fail again in about a fortnight. It does not recover photos taken before the cache was cleared, which is why step one is "check whether any photos are still waiting to sync and send them to the desk first". It does not work on the older tablets. Each of those sentences prevents a reopen, a complaint, or a lost afternoon, and each was learned by someone the hard way. A workaround that leaves them out is a workaround with footnotes that only Farah can read.

Publishing It Where the Technicians Look

A workaround is published when a technician who has never seen the symptom finds it in under a minute from the words in the ticket. That is the whole standard, and it decides where the record lives and what it is called. The place is wherever the desk already looks when stuck. For most, that is an internal section of the knowledge base, the same one that holds the how-to articles. The known errors are marked so they are told apart from ordinary guidance. The title is the symptom in the requester's words, not the cause in the technician's: "Repairs app says 'sync failed' when uploading photos", not "Tablet cache exhaustion on app build". Owen searched for "sync failed". A title with "cache" in it would have been invisible to him.

Tools differ in what they offer, and the standard works with any of them. Some have an internal knowledge base with articles visible only to technicians, which is ideal. Some have only a public one. In that case, the known error gets a public article written for the requester. The technician-only details, such as the admin steps and the root cause notes, stay in the problem record instead. Some have no knowledge base at all. Then a shared folder with one document per known error, named by symptom, does the job, as long as it is the one folder everybody uses. The document and the folder are the second person on a one-person desk, which is the argument of Documentation as Your Second Person, and it applies to a desk of five exactly as well.

Tell the desk when a new known error is published, out loud or in the team chat, in one line: "KE-12 published: tablet photo sync, workaround is clear cache and sign in, one minute." Publishing silently is filing. The line takes ten seconds and means that for the next week every technician recognises the symptom without searching, which is when most of the time is saved. After the week, the search does the work.

Linking Every New Ticket to the Known Error

Every ticket that turns out to be a known error is linked to it, and the link is what keeps the count honest. The count is the business case for the permanent fix. A known error whose tickets are not linked has a count that stops at the day the workaround was written. That is the day the fix stopped looking urgent. Twenty-two tickets at Ashgrove became fifty-one over the next four months, and the fifty-one is what persuaded the supplier to move the app update up a release. Twenty-two would not have.

The mechanics depend on the tool and should be the simplest thing it supports. Some tools have a field or a tag that can hold a known-error number. Some can link tickets to each other. Many have neither. Then the link is a fixed form of words in the resolution note, "KE-12", which a search for "KE-12" finds and counts. Pick one, agree it, and write it on the known-error record so nobody has to remember. The convention that works everywhere is the note. The only rule is that the number is written the same way every time. A search for "KE-12" does not find "KE 12", "ke12" or "the tablet thing".

Link at the moment the workaround is applied, not at the end of the week. The technician has the record open to follow the steps, and adding the number to the note takes five seconds then and five minutes later. On a desk where triage recognises the known error from the ticket's words, the link can be made at triage. The workaround can be sent in the first reply, and the ticket never reaches a technician at all. That is the cheapest a known error ever gets: a recognised symptom, a reply with three steps, and a count that went up by one. The record and its count feed back into the problem record it belongs to, described in Problems vs Incidents, which is the one with the owner and the next-review date.

What to Tell the Requester

The requester hears three things, in one short message: this is a known issue, here is how to get going now, and a permanent fix is planned or under review. "This is a known issue with the repairs app that we are working with the supplier on. To get going now: clear the app's cache, sign out and sign in again, and the sync will complete within a minute. If any photos were taken before this and are still waiting, send them to us first and we will attach them." No apology longer than the explanation, and no promise of a date the desk does not have. Give no explanation of the cause unless the requester asks. The cause is interesting to the desk and not to someone standing in a tenant's kitchen.

Resist the two opposite mistakes. One is pretending each occurrence is new, which costs the requester the same fifty minutes of investigation Owen spent and tells them, the fourth time, that the desk has no memory. The other is promising the fix: "this will be sorted next week" is a promise about a supplier's release schedule. When the week passes, the known error has become a broken promise with a workaround attached. "A fix is planned" is true and sufficient. When the fix has a date, say the date; before that, say the plan.

Where the requester can follow the workaround themselves, publish a requester-facing version and point to it. A known error that requesters can self-serve stops generating tickets at all. The public article is shorter than the technician's record: the symptom, the three steps, the one caution, and "if this does not work, raise a ticket and mention this article". Some desks also list current known errors on a status page or a portal banner. Most small desks do not have one, and a knowledge base article plus a line in the auto-reply does the same job. If the desk is closing a ticket it cannot fix at all, rather than one it can get round, that is a different conversation. It is in Closing the Ticket You Cannot Fix.

Keeping Known Errors Alive, and Retiring Them

A known error is reviewed at the weekly problem hour with three questions. How many tickets linked this week? Is the workaround still working? What is happening with the fix? The first keeps the count moving and the business case current. The second catches the workaround that has quietly stopped working because something else changed, which happens. The technicians will notice it before the owner does if they are asked. The third is the owner's reminder that the comfortable state is temporary. A known error that has had no fix activity for two months gets raised, with its count, by the owner, which is the subject of Getting the Permanent Fix Done.

When the fix goes in, the known error is not deleted. It is marked fixed with the date, and the article stays visible for a watching period with a line at the top: "Fixed on the 14th by the app update; if you see this symptom after that date, raise it with the problem owner." The watching period is where the fix is proved by the tickets stopping, and the article is how a technician knows that a new occurrence is news. After the period, the article is archived rather than removed. The symptom may return in two years when someone reverses the fix without knowing why it was made. An archived article with the cause in it saves the next Owen his fifty minutes all over again.

The failure to watch for is the zombie workaround. The fix went in, the article stayed up with no note, and technicians kept applying the workaround to every similar ticket for a year. So the fix was never proved and a new, different problem with similar words was hidden behind it. The "fixed on" line at the top prevents it. So does the monthly count of tickets linked to each known error, read at the review. That count should fall to zero after a fix and be questioned if it does not. A known error whose count rises after its fix date is either a fix that did not work or a second problem wearing the first one's name. Both deserve the record to be reopened.

A Short War Story: The Card Printer at Bluewater Bank

Bluewater Bank's branch desk supported a card printer in each of fourteen branches. The printer in branch 4 jammed about twice a month in a way that no error code described. Tomas, who had set the printers up, knew the steps: hold the feed button for three seconds, open the lid, reseat the ribbon on the left spindle first. It came back, every time, in two minutes. He never wrote it down, because it was two minutes. Over a year, the other three technicians took that ticket seven times between them. They spent forty minutes to an hour on each before phoning Tomas or giving up and sending an engineer. The branch issued no cards while they tried. When Tomas left, the next jam took a day and a half, two engineer visits and a replacement printer that jammed the same way the following week. This happened because the ribbon had been reseated right spindle first, which nobody now knew was the whole trick. Marta, who took over the desk, wrote the workaround down from a phone call to Tomas at his new job and titled it by the symptom. The next jam took the newest technician two minutes. A workaround that lives in one head is one person's memory, and memory leaves the building with its owner.

The Known-Error Record

The record below is the known-error article as plain text, so it can be pasted into a knowledge base article, a problem record, or a shared document. The title line is the symptom in the requester's words. The recognition test comes before the steps, and the steps are numbered and specific enough for someone in their second week. The "does not" section is where the footnotes go that would otherwise stay in Farah's head. Fill in the linking convention so nobody has to remember it, and keep the count current at the weekly review.

KNOWN ERROR — ONE PAGE
KE number: ________   Problem ID: ________   Owner: ______________
Title (symptom, in the requester's words):
  ___________________________________________________________________
Status: [ ] Workaround published  [ ] Fix scheduled: ________
        [ ] Fixed on: ________, watching until: ________  [ ] Archived

HOW TO RECOGNISE IT
  Exact wording seen: _______________________________________________
  Affects (device, site, group, version): ____________________________
  What the requester was doing: ______________________________________
  Quick check that confirms it: ______________________________________
  Looks similar but is NOT this: ______________________________________

WORKAROUND (tested on: ________  by: ________)
  Who can do it: [ ] requester  [ ] technician remotely  [ ] at the device
  Before you start: __________________________________________________
  1. _________________________________________________________________
  2. _________________________________________________________________
  3. _________________________________________________________________
  How to tell it worked: _____________________________________________
  If it did not work: ________________________________________________
  Time it takes: ______

WHAT THE WORKAROUND DOES NOT DO
  _____________________________________________________________________
  _____________________________________________________________________

CAUSE
  [ ] proved   [ ] probable   [ ] unknown
  _____________________________________________________________________

TELL THE REQUESTER (paste into the reply)
  "This is a known issue that we are ______________. To get going now:
   ______________________. A permanent fix is ______________."
  Requester-facing article: __________ (if they can self-serve)

LINKING
  Write exactly "KE-____" in the resolution note of every ticket.
  Tickets linked: this week ____   this month ____   total ____
  Last reviewed: ________   Next review: ________

Fill the record in on the day the workaround is confirmed, while the steps are fresh and the person who found them is in the room. Publish it the same afternoon. Owen wrote KE-12 at Ashgrove on the Wednesday, from Farah's one-minute description and his own fifty minutes of knowing what did not work. Knowing what did not work turned out to be the most useful part. The record was titled "Repairs app says 'sync failed' when uploading photos", it opened with the storage check, and it was found by the next technician in forty seconds. The app update arrived five months and fifty-one linked tickets later. In those five months nobody on the desk spent more than two minutes on it, and nobody had to walk over to Farah.

Frequently Asked Questions