A Structured Troubleshooting Method
A method that works for any IT problem: identify the problem, form a theory, test it, plan and carry out the fix, verify, and document — and why skipping steps costs more time than it saves.
Why a method beats guessing
Under pressure, the natural reaction to a broken system is to start trying things: restart the service, clear the cache, reinstall the driver, reboot the switch. This is shotgun troubleshooting: changing many things, often at once, in the hope that one of them hits. Sometimes it works. You then do not know which change helped, you may have caused a second problem, and when the fault comes back next month you start from zero.
A method turns troubleshooting into a short series of experiments. You collect facts, form one explanation, test it, and only then change something — one thing at a time. It feels slower for the first ten minutes and is almost always faster over the whole problem. It also makes your work easy to hand over: anyone who reads your notes can see what you ruled out, so the second-line engineer or the next shift does not repeat it.
The method on this page is general. The pages on troubleshooting hardware, operating systems, Linux, networks and identity apply it with the tools of each area; code is covered by a systematic debugging method.
The six steps
Every well-known troubleshooting methodology describes the same cycle in slightly different words. This encyclopedia uses six steps:
1. Identify the problem
Find out what is actually wrong before deciding why. Collect the symptoms, the exact error text, when it started, who and what is affected (one user, a department, everyone), and what changed recently. Try to reproduce it. If a user reports three things at once, split them into separate problems and handle them one by one.
This step is the one most often rushed, and the one that decides how fast the rest goes. It has its own page: asking good questions and gathering information.
2. Establish a theory of probable cause
A theory of probable cause is a specific, testable explanation of the symptoms: not "something with the network", but "the new DNS server for this office does not forward queries for the internal zone". A good theory explains all the facts — including the ones that do not fit an easy story, such as "but the colleague next to her has no problem".
Three habits make theories better:
- Ask what changed. A system that worked yesterday and fails today usually had something change in between: an update, a configuration change, a new certificate, a moved server, a password expiry, a full disk. Check the change schedule and the logs before inventing exotic causes.
- Question the obvious. Is it plugged in, switched on, licensed, not expired, not out of disk space? Is the user typing the right address? Checking takes seconds, and experienced engineers check these first because they are common, not because users are careless.
- Research. Search the knowledge base, known errors and vendor documentation; someone has probably seen it before. How to read error messages and judge sources is on reading errors, logs and documentation.
When several theories fit, Occam's razor — named after the fourteenth-century philosopher William of Ockham — says to prefer the explanation that needs the fewest assumptions. "The certificate expired last night" beats "a rare kernel bug triggered by the full moon". Occam's razor is a rule for where to look first, not proof: if the simple theory fails its test, move on.
3. Test the theory to determine the cause
Test before you fix. A good test is safe (it does not change production), quick, and can clearly fail: if the theory is "DNS", resolve the name against the suspect server and against a known-good one, and compare. If the theory is confirmed, you move on to planning. If not, it is not wasted: you have ruled something out. Form a new theory with what you learned, or escalate.
Change only one thing per test. If you clear the cache and restart the service and update the driver, and the problem disappears, you have learned nothing about the cause.
4. Plan the fix and implement it
A plan of action describes how you will fix the confirmed cause: the steps, who does them, when, what it affects, and how you will undo them if they go wrong. For a single laptop the plan may be one sentence in your head. For a shared system it is written down, and usually goes through change management: a change request, approval, a maintenance window if users are affected, and a rollback plan. See change enablement and working safely on production systems.
Before you change anything: make a backup or export of what you will change, and know the way back. If the fix needs rights or knowledge you do not have, the plan is to escalate.
5. Verify full system functionality
Full system functionality means the whole task the user needed works again, not only the symptom you were looking at. After fixing a printer driver, print the user's actual document from their actual application; after fixing DNS, check the intranet and the other internal sites and the Internet. Ask the user to confirm — they know their work better than you do.
This is also the moment for preventive measures: can you stop it happening again, or on other machines? Add a monitoring check, update a checklist, open a problem record for a recurring fault (see problem management).
6. Document findings, actions and outcomes
Record what you found, what you did and what the result was — ideally as you go, not from memory afterward. Good notes let a colleague continue your ticket, let the next person with the same problem find the answer in the knowledge base, and make patterns visible. How to write them is on writing tickets and technical documentation.
Half-splitting
When there are many possible places for a fault — eight changes made last week, ten devices on a network path, a thousand lines of configuration — testing them one by one is slow. Half-splitting (also called divide and conquer) tests in the middle instead. If the middle is fine, the fault is in the second half; if not, it is in the first half. Each test halves what is left, so eight candidates need at most three tests and a thousand need about ten. Network engineers do this with a ping from the middle of the path; developers do it with git bisect.
Here, the Kestrel Energy customer portal broke in the test environment after last week's eight changes were applied. Each change can be applied in order, so the question is: which is the first one after which the portal fails?
# Changes applied to the portal servers last week, oldest first
changes = [
"CHG-2101 rotate TLS certificate",
"CHG-2102 raise log level to INFO",
"CHG-2103 patch web server",
"CHG-2104 new firewall rule for backups",
"CHG-2105 move session store to new host",
"CHG-2106 update login library",
"CHG-2107 tune database pool size",
"CHG-2108 add health-check endpoint",
]
def portal_works(applied):
"""Stand-in for a real test in a test environment."""
return "CHG-2105 move session store to new host" not in applied
good, bad = 0, len(changes) # 0 changes applied: works; all applied: broken
tests = 0
while bad - good > 1:
middle = (good + bad) // 2
tests += 1
works = portal_works(changes[:middle])
print(f"Test {tests}: first {middle} changes applied ->", "works" if works else "BROKEN")
if works:
good = middle
else:
bad = middle
print("First bad change:", changes[bad - 1])
print(f"Found in {tests} tests instead of up to {len(changes)}")Test 1: first 4 changes applied -> works Test 2: first 6 changes applied -> BROKEN Test 3: first 5 changes applied -> BROKEN First bad change: CHG-2105 move session store to new host Found in 3 tests instead of up to 8
Half-splitting needs one condition: you must be able to test "up to here". For a network path that is a ping or traceroute to a midpoint; for changes, a test environment where you can apply them in order. If tests are expensive or risky, half-splitting saves the most.
When to stop and escalate
Escalating is a normal step of the method, not a failure. Escalate when:
- your theories are used up, or the next test needs access or knowledge you do not have;
- the fix would need a change you are not authorized to make;
- the impact is growing — more users, a critical service, signs of a security incident;
- you have reached the time you agreed for this priority. Many teams use a rough rule such as "no progress in 30 minutes on an urgent ticket: ask".
A good escalation hands over your work, not just the problem: symptoms, scope, what you tested and what it showed, and what you think is next. Then the second line starts at step 3 instead of step 1. Escalation paths are described on the service desk, and on-call escalation on handovers, shift work and on-call.
A worked example
A morning at Kestrel Energy. Several users in the Utrecht office report that the intranet does not open. Amara Okafor on the service desk takes the first call; Tomasz Nowak in the NOC joins later. Their ticket shows every step:
INC-20502 Intranet not reachable - Utrecht office 1 IDENTIFY 08:20 Since about 08:00, users in Utrecht get "This site can't be reached" for intranet.example.com. 12 calls, all Utrecht, wired and Wi-Fi. Rotterdam and remote users are fine. Utrecht users CAN open external sites and the intranet by IP address (192.0.2.40). So: name resolution, Utrecht only. What changed: CHG-2117 last night moved Utrecht to a new DNS server (198.51.100.53). 2 THEORY 08:35 The new Utrecht DNS server does not resolve the internal zone (simplest explanation that fits all facts). 3 TEST 08:40 Lookup of intranet.example.com: - against old DNS server 192.0.2.53: 192.0.2.40 (ok) - against new DNS server 198.51.100.53: no answer Theory confirmed. Escalated to NOC (Tomasz) - DNS servers are theirs. 4 PLAN + IMPLEMENT 08:55 (Tomasz) New server misses the forwarder for the internal zone. Plan: add forwarder (emergency change CHG-2119, approved by the emergency change authority). Rollback: point Utrecht DHCP back to the old server. Implemented 09:10. 5 VERIFY 09:15 From two Utrecht PCs: intranet, HR portal and ticket system open by name; external sites still fine. Three callers confirm. Preventive: forwarder check added to the DNS migration checklist (KB-0416 updated). 6 DOCUMENT 09:25 Resolved. Cause: missing forwarder after CHG-2117. Linked CHG-2117 and CHG-2119; review of the migration checklist requested from NOC.
Note what did not happen: nobody restarted the users' PCs, cleared browser caches or reinstalled anything. The scope ("Utrecht only, by name only") and the recent change pointed straight at a testable theory. Fifty-five minutes from first call to fix, and the cause is on record.
Common traps
- Fixing the symptom only. A restart that makes the problem go away is a fine workaround, but write it down as a workaround and keep looking for the cause, or open a problem record.
- Falling in love with the first theory. Once you have an explanation, it is tempting to ignore facts that do not fit. If something does not fit, the theory is incomplete. Under stress this gets worse; see working under pressure.
- Confusing "at the same time" with "because of". The update installed on Tuesday and the problem started on Tuesday — that makes the update a good theory, not a proven cause. Test it.
- Verifying from your own point of view. "It works on my machine" or "the service is running" is not the same as "the user can do their work".
- Skipping documentation because it was "only small". Small problems repeat. A two-line note now saves the next person twenty minutes.