Free reference
The troubleshooting ladder
A method, not a command list. Work up the stack one layer at a time, then use the fast path, because knowing what a failure at each step tells you is most of the job.
WORK UP THE STACK
1 PHYSICAL
Link light on. Cable seated at both ends. Right port, right jack, right outlet. Power, PoE, the switch on the surge strip.
2 LINK
ip link, arp -a. Correct VLAN on the switch port. Speed and duplex matched. Is the MAC even showing up.
3 NETWORK
ip a, do you have an address at all. 169.254 means DHCP never answered. ip r, is there a default route. Ping the gateway, then ping 8.8.8.8. Check the mask.
4 TRANSPORT
nc -zv host 443, is the port open. ss -tulpn, is anything listening. Firewall, security group, ACL, host-based rules.
7 APPLICATION
dig host, does the name resolve. Certificate still valid. Credentials, token, session. What HTTP status came back. Read the actual log line, not the summary.
THE FAST PATH
| 1 Ping the gateway | Fails: local. Cable, port, VLAN, DHCP, mask. |
| 2 Ping 8.8.8.8 | Fails: routing, NAT or upstream. |
| 3 dig google.com | Fails: DNS. |
| 4 nc -zv host port | Fails: firewall, or the service is down. |
| 5 curl -v https://host | Fails: TLS, certificate or the app. |
| 6 All five pass | It is the application, or it is layer 8. |
SCOPE IT BEFORE YOU DIG
One user, or everyone.
One site, or every site.
Since when. And what changed.
QUESTIONS THAT HELP
What exactly did you click, in order?
What did you expect to happen instead?
WHEN IT IS ONE USER
| Works on another machine | Their machine, not their account. |
| Works for another user there | Their profile or local config. |
| Works in a private window | Cache, cookies or an extension. |
| Works on their phone | The laptop, or the office network. |
| Works off the VPN | Split DNS, proxy or a firewall rule. |
WHEN IT IS EVERYONE
| Started on a round number hour | A scheduled job, a token, or a certificate. |
| Started right after a change | Roll it back, then debug it. |
| Only external users | Public DNS, firewall, load balancer, cert. |
| Slow, not failing | Capacity, a queue, or a full disk. |
| Half of requests fail | One node in the pool is bad. Pull it. |
BEFORE YOU ESCALATE
Capture all of it or the ticket comes straight back to you.
Timestamp, with the timezone.
The exact error text. Not a paraphrase.
When it last worked.
What changed. Deploy, patch, config, cert, DNS, firewall.
Steps to reproduce, numbered.
What you already tried and what it did.
SEVERITY, PLAINLY
| P1 | Down or unusable for everyone. Now. |
| P2 | Major function broken, or one customer down hard. |
| P3 | Degraded and ugly, but there is a workaround. |
| P4 | Annoying. Cosmetic. Schedule it. |
The parts people get wrong
These are the distinctions that cost real time. They are the reason this sheet exists rather than another list of commands.
Handling an “it doesn’t work” ticket
It doesn't work is not a symptom. Ask what they expected to happen instead, and you usually have the answer.
Severity vs urgency
Severity is impact times reach. Urgency is how loudly someone is asking. They are different fields and should stay that way.
Troubleshooting an intermittent problem
Intermittent means you have not found the pattern yet. Write down the timestamps and the pattern shows up.
Why you change one thing at a time
Change two things at once and you learn nothing. Change one, test, then the next.
The reboot fixed it but you still do not know why
If a reboot fixed it you still do not know why, and it will be back. Note what you saw before you rebooted.
It works for me but not for the user
Compare account, permissions, network, browser, version, timezone. In that order.