Network Troubleshooting Guide

This is an original planning guide. It is not a vendor manual, an official standard, or legal advice. Example addresses use documentation ranges. Review every command before you paste it.

Troubleshoot in an order you can explain

Start at the symptom and walk toward the cause. Physical link, VLAN, address, gateway, route, name, application. You may skip a layer when the evidence is already in the ticket, and you should say which layer you skipped. You should not start by restarting a core router because one laptop cannot open a website.

The tools on this desk can ping, trace, or check a port when those tools are the ones that send packets, and some pages only build a command or read a paste. Read the page. If it says it does not probe, it does not probe. Do not point a home-made scan at a network you do not operate. Troubleshooting here means narrowing a fault you are responsible for.

One change at a time. If you move the VLAN, replace the cable, and flush DNS in the same minute, you will not know which one fixed it, and you cannot undo it cleanly. The second change belongs in the ticket as a later step.

Write the last known good. A closet that failed after a trunk edit is a different incident from a closet that never worked. The first is a rollback. The second is a build. Treating a build as a rollback wastes the window, and treating a rollback as a redesign makes the outage longer.

Symptoms and the layer they usually belong to

When you see no link light, the likely place is the cable, the optic, the port shutdown, or the wrong patch. It is rarely the subnet mask. The useful next step is: move one patch and watch the light before you change a VLAN. Change one thing, then test the same way you tested before. A ticket that says the network is down is not a symptom. A ticket that says this host, this address, this gateway, this name, and this port is a symptom. Write those five before you ask for a maintenance window. If you cannot ping, say whether the gateway answers and whether a neighbour answers. If you can ping and the application fails, say the port. ICMP success does not mean TCP 443 is open, and an open port does not mean the certificate is the one the user trusts. Keep the layer you have not proved out of the theory.

When you see link light and no DHCP, the likely place is the VLAN, the helper, the scope, or the trunk. It is rarely the public DNS resolver. The useful next step is: confirm the access VLAN and that one static address in the same subnet works. Change one thing, then test the same way you tested before. A ticket that says the network is down is not a symptom. A ticket that says this host, this address, this gateway, this name, and this port is a symptom. Write those five before you ask for a maintenance window. If you cannot ping, say whether the gateway answers and whether a neighbour answers. If you can ping and the application fails, say the port. ICMP success does not mean TCP 443 is open, and an open port does not mean the certificate is the one the user trusts. Keep the layer you have not proved out of the theory.

When you see static address and no gateway ping, the likely place is the mask, the VLAN, or a missing SVI. It is rarely an application timeout. The useful next step is: ping the gateway from the host, then ping the host from the gateway. Change one thing, then test the same way you tested before. A ticket that says the network is down is not a symptom. A ticket that says this host, this address, this gateway, this name, and this port is a symptom. Write those five before you ask for a maintenance window. If you cannot ping, say whether the gateway answers and whether a neighbour answers. If you can ping and the application fails, say the port. ICMP success does not mean TCP 443 is open, and an open port does not mean the certificate is the one the user trusts. Keep the layer you have not proved out of the theory.

When you see gateway ping works and nothing else does, the likely place is a route, an ACL, or a return path. It is rarely the Ethernet cable you already proved. The useful next step is: pick one internal address and one external address and see which side fails. Change one thing, then test the same way you tested before. A ticket that says the network is down is not a symptom. A ticket that says this host, this address, this gateway, this name, and this port is a symptom. Write those five before you ask for a maintenance window. If you cannot ping, say whether the gateway answers and whether a neighbour answers. If you can ping and the application fails, say the port. ICMP success does not mean TCP 443 is open, and an open port does not mean the certificate is the one the user trusts. Keep the layer you have not proved out of the theory.

When you see one direction works, the likely place is stateful policy, asymmetric routing, or a missing reverse route. It is rarely a new SSID. The useful next step is: draw both directions. A path that works one way is still broken. Change one thing, then test the same way you tested before. A ticket that says the network is down is not a symptom. A ticket that says this host, this address, this gateway, this name, and this port is a symptom. Write those five before you ask for a maintenance window. If you cannot ping, say whether the gateway answers and whether a neighbour answers. If you can ping and the application fails, say the port. ICMP success does not mean TCP 443 is open, and an open port does not mean the certificate is the one the user trusts. Keep the layer you have not proved out of the theory.

When you see DNS fails and the IP works, the likely place is the resolver, the suffix, or the record. It is rarely the switchport. The useful next step is: connect by address. If that works, stop editing the VLAN and edit DNS. Change one thing, then test the same way you tested before. A ticket that says the network is down is not a symptom. A ticket that says this host, this address, this gateway, this name, and this port is a symptom. Write those five before you ask for a maintenance window. If you cannot ping, say whether the gateway answers and whether a neighbour answers. If you can ping and the application fails, say the port. ICMP success does not mean TCP 443 is open, and an open port does not mean the certificate is the one the user trusts. Keep the layer you have not proved out of the theory.

When you see names work and the application does not, the likely place is the port, the certificate, the proxy, or the service. It is rarely the subnet calculator. The useful next step is: name the TCP port and test that port, not just ICMP. Change one thing, then test the same way you tested before. A ticket that says the network is down is not a symptom. A ticket that says this host, this address, this gateway, this name, and this port is a symptom. Write those five before you ask for a maintenance window. If you cannot ping, say whether the gateway answers and whether a neighbour answers. If you can ping and the application fails, say the port. ICMP success does not mean TCP 443 is open, and an open port does not mean the certificate is the one the user trusts. Keep the layer you have not proved out of the theory.

When you see only one user is broken, the likely place is that user's address, VLAN, or proxy setting. It is rarely a core route. The useful next step is: compare the working neighbour on the same switch port VLAN before you touch the core. Change one thing, then test the same way you tested before. A ticket that says the network is down is not a symptom. A ticket that says this host, this address, this gateway, this name, and this port is a symptom. Write those five before you ask for a maintenance window. If you cannot ping, say whether the gateway answers and whether a neighbour answers. If you can ping and the application fails, say the port. ICMP success does not mean TCP 443 is open, and an open port does not mean the certificate is the one the user trusts. Keep the layer you have not proved out of the theory.

When you see a whole closet is broken, the likely place is the uplink, the trunk, or the closet switch. It is rarely a single laptop driver. The useful next step is: see whether the gateway SVI is up and whether other closets are fine. Change one thing, then test the same way you tested before. A ticket that says the network is down is not a symptom. A ticket that says this host, this address, this gateway, this name, and this port is a symptom. Write those five before you ask for a maintenance window. If you cannot ping, say whether the gateway answers and whether a neighbour answers. If you can ping and the application fails, say the port. ICMP success does not mean TCP 443 is open, and an open port does not mean the certificate is the one the user trusts. Keep the layer you have not proved out of the theory.

When you see it broke after a change, the likely place is the change. It is rarely a theory about the carrier. The useful next step is: undo the change or compare the ticket to the device before you add a second change. Change one thing, then test the same way you tested before. A ticket that says the network is down is not a symptom. A ticket that says this host, this address, this gateway, this name, and this port is a symptom. Write those five before you ask for a maintenance window. If you cannot ping, say whether the gateway answers and whether a neighbour answers. If you can ping and the application fails, say the port. ICMP success does not mean TCP 443 is open, and an open port does not mean the certificate is the one the user trusts. Keep the layer you have not proved out of the theory.

When you see it is slow, the likely place is loss, a duplex mismatch, a full link, or a bad path. It is rarely a DNS TTL. The useful next step is: measure loss and the used bandwidth. Slow is not a VLAN id. Change one thing, then test the same way you tested before. A ticket that says the network is down is not a symptom. A ticket that says this host, this address, this gateway, this name, and this port is a symptom. Write those five before you ask for a maintenance window. If you cannot ping, say whether the gateway answers and whether a neighbour answers. If you can ping and the application fails, say the port. ICMP success does not mean TCP 443 is open, and an open port does not mean the certificate is the one the user trusts. Keep the layer you have not proved out of the theory.

When you see it works on VPN and not in the office, the likely place is split horizon, a route, or an internal name. It is rarely the laptop hardware. The useful next step is: compare the address and the resolver on and off the VPN. Change one thing, then test the same way you tested before. A ticket that says the network is down is not a symptom. A ticket that says this host, this address, this gateway, this name, and this port is a symptom. Write those five before you ask for a maintenance window. If you cannot ping, say whether the gateway answers and whether a neighbour answers. If you can ping and the application fails, say the port. ICMP success does not mean TCP 443 is open, and an open port does not mean the certificate is the one the user trusts. Keep the layer you have not proved out of the theory.

When you see it works in the office and not on VPN, the likely place is the VPN pool overlapping the office, or a missing route. It is rarely the access switch. The useful next step is: check whether the VPN addresses collide with 192.168.0.0/16 or with the office prefix. Change one thing, then test the same way you tested before. A ticket that says the network is down is not a symptom. A ticket that says this host, this address, this gateway, this name, and this port is a symptom. Write those five before you ask for a maintenance window. If you cannot ping, say whether the gateway answers and whether a neighbour answers. If you can ping and the application fails, say the port. ICMP success does not mean TCP 443 is open, and an open port does not mean the certificate is the one the user trusts. Keep the layer you have not proved out of the theory.

When you see a wireless client fails and a wired one works, the likely place is the SSID VLAN, the DHCP scope, or RF. It is rarely OSPF. The useful next step is: put the wireless VLAN beside the wired one in the ticket and prove which gateway it uses. Change one thing, then test the same way you tested before. A ticket that says the network is down is not a symptom. A ticket that says this host, this address, this gateway, this name, and this port is a symptom. Write those five before you ask for a maintenance window. If you cannot ping, say whether the gateway answers and whether a neighbour answers. If you can ping and the application fails, say the port. ICMP success does not mean TCP 443 is open, and an open port does not mean the certificate is the one the user trusts. Keep the layer you have not proved out of the theory.

A worked incident: one floor cannot reach the file server

The ticket says the second floor cannot open the file server. It does not say the network is down. You find that second-floor hosts have 198.51.100.0/26 addresses and can ping 198.51.100.1. They cannot ping 203.0.113.10, which is the file server in the documentation range for this example. A host on the first floor, 198.51.100.80, can ping the file server. So the server is up, and the path from the first floor works.

The second floor is 198.51.100.0/26 and the first floor is 198.51.100.64/26. Both should use the core. The second floor's gateway answers, so the SVI and the VLAN are alive. A traceroute from a second-floor host stops at the gateway, while the first floor goes further. Look at the route and the policy on the gateway for 198.51.100.0/26 specifically. A missing route or an ACL that names only the /26 of the first floor fits the evidence. An ACL that blocked everyone would have broken the first floor too.

You do not swap the core. You compare the two prefixes in the policy, add the missing one if the ticket says the second floor should have access, and test one host. Then you test a name, not only an address, in case the file server name points somewhere else. Then you tell the floor to retry. The cable plant did not need a visit.

If the gateway had not answered, you would have stopped at the VLAN and the SVI instead. The same ticket, with one different observation, is a different layer. That is why the first test is the gateway and not the file-server vendor.

What to write down before you change anything

Host address and mask, default gateway, whether the gateway pings, whether the neighbour pings, the name you used, and the port the application needs. Add the time and the closet or SSID. That list is short enough to demand and long enough to stop a guess.

Keep a rollback. If the change is a trunk allowed-list, the rollback is the previous list, not a reboot. If the change is a firewall object, the rollback is the previous object. Reboots hide the evidence and drop unrelated sessions.

When it is fixed, write the layer and the change in one sentence. Future you will search for that sentence. A closed ticket that says resolved is how the same outage gets a new engineer next quarter.

Rewrite the symptom as a host, an address, a gateway, a name, and a port.
Test the nearest layer you have not proved.
Compare with a neighbour that works.
Make one change that the comparison justifies.
Retest the same five facts.
Record the layer and the rollback.

Mistakes that make the outage longer

Changing the core because one closet failed.

Calling DNS broken because a browser failed, without trying the address.

Calling the cable broken because a ping failed, without checking the link light.

Applying a second fix before the first test finished.

Scanning a subnet to see who is alive. Ask the inventory or the switch table you already operate.

Restarting a firewall as a diagnostic.

Mixing a user report from VPN with a user report from the office and calling them one fault.

Closing the ticket without the sentence that says which layer it was.

Declaring the WAN down because one application failed, before anyone pinged the gateway from the affected host.

Tools for this guide

These tools run in the browser on this site. They do not log into your machines.

Guides in this cluster

These supporting pages belong to this pillar.