SONiC

Troubleshooting Center

SONiC troubleshooting is layered: intent has to travel down a ladder, and your job is to find the rung where it stopped. Pick a symptom to get the layers, first commands, evidence, and a branching plan.

The troubleshooting ladder

  1. 1Intended configurationlikely
  2. 2CONFIG_DBlikely
  3. 3Service healthlikely
  4. 4Protocol statelikely
  5. 5APPL_DB
  6. 6Dependency resolutionlikely
  7. 7SWSS & orchagent processing
  8. 8SAI & syncd
  9. 9ASIC_DB
  10. 10Hardware counters
  11. 11Packet capture
  12. 12End-to-end forwarding

Highlighted rungs are the layers most likely involved in the selected symptom.

Select a symptom

BGP neighbor down

A configured BGP session will not reach Established. Because BGP in SONiC is FRR (bgpd) inside the bgp container, the fault can sit anywhere from intent, through the bgp service, down to underlay reachability for the peer address.

Start here

SONiC CLI
show ip bgp summary
FRR / vtysh
vtysh -c 'show bgp neighbors <peer> '
SONiC DBCONFIG_DB intent for this neighbor
redis-cli -n 4 HGETALL 'BGP_NEIGHBOR|<peer>'
Linux
ping <peer>

Expected evidence

  • Session state in FRR (Idle / Active / Connect / OpenSent / Established) and the timers/reason for the last reset.
  • CONFIG_DB holds the neighbor with the expected remote-AS, update-source, and address family.
  • Underlay reachability to the peer IP, and that TCP/179 is not filtered.

Common causes

  • Remote-AS or local-AS mismatch, or a typo in the neighbor address.
  • Wrong or missing update-source / no route to the peer loopback.
  • Peer IP unreachable in the underlay (interface down, missing route).
  • ACL or control-plane rate-limit dropping TCP/179.
  • Address family not activated for the neighbor.

Branching diagnostics

Is the peer IP reachable (ping / route present)?

Yes → Underlay is fine — move to protocol state: compare local vs remote AS, addresses, and negotiated address families in show bgp neighbors.

No → Fix dependency resolution first: interface/oper state, the route to the peer, and any ACL/control-plane policer dropping TCP/179.

Does FRR show the session but stuck in Active/Connect (never OpenSent)?

Yes → TCP is not completing — suspect an ACL, a wrong update-source, or the peer not listening; capture on TCP/179 if needed.

No → If it reaches OpenSent/OpenConfirm then flaps, look at capability/AS/hold-timer mismatch in the neighbor log.

Is the bgp container actually healthy and is FRR configured as expected?

Yes → Trust FRR state and keep working the protocol layer.

No → If the bgp container is restarting or bgpd did not read config, fix service health before interpreting protocol output.

Recovery

  • Correct the mismatched attribute in CONFIG_DB (or FRR config) and let the session re-establish.
  • Restore underlay reachability (interface, route, or ARP/ND) to the peer address.
  • Remove or correct the filtering ACL / policer; re-test with a targeted capture.

What not to do

  • Do not restart the bgp container on a production switch to 'kick' a session — without warm-restart configured this can drop every session on the box; behavior varies by version and config.
  • Do not assume the peer is at fault before confirming your own local-AS, update-source, and reachability.