Courseiva
DebugPrivileged EXEC

debug spanning-tree events

Enables debugging of Spanning Tree Protocol (STP) state transitions and topology change events to troubleshoot STP convergence issues.

Definition: debug spanning-tree events is a Cisco IOS privileged exec command. Enables debugging of Spanning Tree Protocol (STP) state transitions and topology change events to troubleshoot STP convergence issues.

Overview

The `debug spanning-tree events` command is a powerful diagnostic tool used in Cisco IOS to monitor Spanning Tree Protocol (STP) state transitions and topology change events in real time. STP is a Layer 2 protocol that prevents loops in Ethernet networks by creating a loop-free logical topology. When a link or switch fails, or when a new switch is added, STP recalculates the topology, which involves transitions between blocking, listening, learning, and forwarding states.

These transitions can cause temporary network outages if not properly managed. This debug command allows network engineers to observe every state change, topology change notification (TCN), and related event as they happen. It is invaluable for troubleshooting convergence issues, such as slow STP convergence, unexpected topology changes, or flapping ports.

Unlike `show spanning-tree` commands, which provide a static snapshot, `debug spanning-tree events` offers dynamic, real-time insight into the STP process. However, it should be used with caution because debug output is CPU-intensive and can overwhelm the console or buffer, especially in large networks. The command requires privileged EXEC mode (enable) and does not affect the running configuration; it is a runtime diagnostic only.

Output is sent to the console or can be redirected to a buffer using `logging buffered`. To stop debugging, use `undebug spanning-tree events` or `no debug spanning-tree events`. This command is typically used during maintenance windows or in lab environments to avoid disrupting production traffic.

It is a go-to tool when STP-related issues are suspected, such as when a port remains in blocking state longer than expected, or when the network experiences intermittent connectivity due to topology changes. By correlating debug output with other show commands like `show spanning-tree` and `show interfaces`, engineers can pinpoint misconfigurations, hardware failures, or design flaws. Understanding STP events is crucial for CCNA and CCNP candidates, as it forms the foundation for more advanced topics like Rapid PVST+, MST, and EtherChannel.

This debug command works across all Cisco IOS platforms that support STP, including switches and routers with Layer 2 capabilities. It is also available in IOS-XE, though output formatting may differ slightly. In NX-OS, the equivalent is `debug spanning-tree events` as well, but with different output syntax.

For ASA firewalls, STP debugging is not directly applicable as they operate at Layer 3. Overall, mastering this command equips network professionals with the ability to diagnose and resolve STP issues efficiently, ensuring network stability and performance.

Syntax·Privileged EXEC
debug spanning-tree events

When to Use This Command

  • Investigating why a switch is unexpectedly blocking or forwarding ports in a redundant topology.
  • Troubleshooting frequent topology changes causing network instability or MAC address flapping.
  • Verifying that STP converges correctly after adding or removing links in a switched network.
  • Diagnosing why a specific port is not transitioning from blocking to forwarding state.

Command Examples

Basic debug spanning-tree events output

debug spanning-tree events
STP: VLAN0001 new root addr 0011.2233.4455, priority 32769
STP: VLAN0001 Topology Change rcvd on Gi0/1
STP: VLAN0001 Gi0/1 -> blocking
STP: VLAN0001 Gi0/2 -> listening
STP: VLAN0001 Gi0/2 -> learning
STP: VLAN0001 Gi0/2 -> forwarding
STP: VLAN0001 Gi0/1 -> listening
STP: VLAN0001 Gi0/1 -> learning
STP: VLAN0001 Gi0/1 -> forwarding

Each line shows an STP event: root bridge change, topology change received, or port state transitions. 'new root addr' indicates a new root bridge election. 'Topology Change rcvd' means a TCN was received. Port states progress from blocking to listening to learning to forwarding.

Debug spanning-tree events with topology change details

debug spanning-tree events
STP: VLAN0001 Topology Change rcvd on Gi0/1
STP: VLAN0001 Topology Change rcvd on Gi0/2
STP: VLAN0001 Topology Change rcvd on Gi0/3
STP: VLAN0001 Topology Change rcvd on Gi0/4
STP: VLAN0001 Topology Change rcvd on Gi0/5
STP: VLAN0001 Topology Change rcvd on Gi0/6
STP: VLAN0001 Topology Change rcvd on Gi0/7
STP: VLAN0001 Topology Change rcvd on Gi0/8

Multiple topology change notifications on many ports indicate a flapping link or a device repeatedly sending TCNs, which can cause MAC address table flushes and network instability.

Understanding the Output

The debug output displays STP events in real time. Each line starts with 'STP:' followed by the VLAN ID. Key events include 'new root addr' (a new root bridge has been elected), 'Topology Change rcvd' (a topology change notification was received on a port), and port state transitions (blocking, listening, learning, forwarding).

A healthy network should show occasional topology changes only when links are added or removed. Frequent or repeated topology changes indicate a problem such as a flapping link, a misconfigured port, or a device generating excessive TCNs. Watch for rapid state transitions or many TCNs on multiple ports, which can degrade network performance.

Configuration Scenarios

Troubleshooting Slow STP Convergence After Link Failure

A network engineer notices that after a link failure between two switches, the backup link takes longer than expected to transition to forwarding state, causing a temporary outage. The goal is to observe STP state transitions in real time to identify delays.

Topology

SW1(Gi0/1)---10.0.1.0/24---(Gi0/1)SW2 SW1(Gi0/2)---10.0.2.0/24---(Gi0/2)SW2

Steps

  1. 1.Step 1: Enter privileged EXEC mode on SW1: SW1> enable
  2. 2.Step 2: Enable debugging for STP events: SW1# debug spanning-tree events
  3. 3.Step 3: Simulate a link failure by shutting down the primary interface: SW1# configure terminal; SW1(config)# interface gigabitethernet0/1; SW1(config-if)# shutdown
  4. 4.Step 4: Observe the debug output showing state transitions on the backup interface (Gi0/2). Look for timestamps and state changes from blocking to listening, learning, and forwarding.
  5. 5.Step 5: After capturing sufficient output, disable debugging: SW1# undebug spanning-tree events
Configuration
! No configuration is changed; only debug is enabled
SW1# debug spanning-tree events
SW1# configure terminal
Enter configuration commands, one per line.  End with CNTL/Z.
SW1(config)# interface gigabitethernet0/1
SW1(config-if)# shutdown
SW1(config-if)# end
SW1#

Verify: The debug output will show lines like: 'STP: VLAN0001 new root port Gi0/2, cost 4' and 'STP: VLAN0001 Gi0/2 -> listening' then 'learning' then 'forwarding'. Expected healthy output shows transitions within a few seconds (default forward delay 15 seconds).

Watch out: If the backup port is configured with PortFast, it will skip listening and learning states, which may mask STP convergence issues. Ensure PortFast is only used on access ports.

Identifying Excessive Topology Changes Due to Flapping Port

A network administrator observes frequent MAC address table flushes and intermittent connectivity issues. The suspicion is that a port is flapping (going up/down repeatedly), causing STP topology change notifications (TCNs) that disrupt the network. The debug command will reveal TCN events.

Topology

SW1(Gi0/1)---10.0.1.0/24---(Gi0/1)SW2 SW1(Gi0/2)---10.0.3.0/24---(Gi0/2)SW3

Steps

  1. 1.Step 1: Enter privileged EXEC mode on SW1: SW1> enable
  2. 2.Step 2: Enable debugging for STP events: SW1# debug spanning-tree events
  3. 3.Step 3: Monitor the console for TCN messages. A flapping port will generate repeated 'STP: VLAN0001 topology change detected' messages.
  4. 4.Step 4: Identify the offending port by correlating TCN timestamps with interface logs using 'show log' or 'show interfaces'.
  5. 5.Step 5: Once the flapping port is identified, disable debugging: SW1# undebug spanning-tree events
Configuration
! Debug enabled to capture TCN events
SW1# debug spanning-tree events
SW1#

Verify: Healthy output shows occasional TCNs (e.g., when a link changes state). Problem indicators include frequent TCNs (multiple per second) from the same VLAN. The debug output will show 'STP: VLAN0001 topology change detected' repeatedly.

Watch out: TCNs can also be caused by PortFast-enabled ports transitioning up/down. Use 'spanning-tree portfast' only on end-user ports. Also, ensure 'spanning-tree bpduguard enable' is configured on access ports to prevent rogue BPDUs.

Troubleshooting with This Command

When using `debug spanning-tree events` for troubleshooting, it is essential to understand what constitutes healthy versus problematic output. Healthy STP behavior shows occasional state transitions when a link changes state, with each transition occurring within the expected forward delay (default 15 seconds for listening and learning each). For example, a port moving from blocking to forwarding should show: 'STP: VLAN0001 Gi0/2 -> listening', then after 15 seconds 'STP: VLAN0001 Gi0/2 -> learning', then after another 15 seconds 'STP: VLAN0001 Gi0/2 -> forwarding'.

In Rapid PVST+, transitions are much faster (a few seconds). Problem indicators include: (1) Repeated 'topology change detected' messages for the same VLAN within short intervals, indicating a flapping link or a PortFast-enabled port bouncing. (2) Ports stuck in listening or learning state for longer than the forward delay, which may indicate a configuration issue like inconsistent port costs or priority. (3) 'Root port change' messages occurring frequently, suggesting instability in the root bridge election. (4) 'BPDU: received' messages with unexpected values (e.g., lower bridge ID than current root) that may indicate a rogue switch. To diagnose, follow this step-by-step flow: First, enable the debug during a maintenance window or on a lab replica.

Second, reproduce the issue (e.g., disconnect a cable, trigger a topology change). Third, capture the output and look for timestamps and state transitions. Fourth, correlate with `show spanning-tree` to verify the current root bridge, port roles, and costs.

Fifth, check `show interfaces` for errors or flapping counters on suspected ports. Sixth, if TCNs are excessive, use `show spanning-tree detail` to see the number of topology changes. Additionally, use `debug spanning-tree bpdu` to inspect BPDU contents if misconfiguration is suspected.

Remember that debug output is CPU-intensive; always limit the scope using `debug spanning-tree events vlan <vlan-id>` if possible (though this subcommand may not be available in all IOS versions). Also, consider using `logging buffered 10000` to capture output to a buffer instead of the console, reducing CPU impact. After troubleshooting, disable all debugging with `undebug all`.

By mastering this debug command, engineers can quickly isolate STP convergence problems and implement corrective actions such as adjusting timers, configuring PortFast, or redesigning the topology.

CCNA Exam Tips

1.

CCNA exam tip: Remember that 'debug spanning-tree events' is a privileged EXEC command and can impact CPU; always use 'undebug all' to disable.

2.

CCNA exam tip: The exam may ask you to interpret debug output to identify a flapping port or excessive topology changes.

3.

CCNA exam tip: Know that STP port states progress in order: blocking, listening, learning, forwarding (or disabled).

4.

CCNA exam tip: Understand that a topology change causes switches to shorten MAC address aging timers to 15 seconds (default) to flush stale entries.

Common Mistakes

Mistake 1: Leaving debug enabled on a production switch, causing high CPU usage and potential packet loss.

Mistake 2: Confusing 'debug spanning-tree events' with 'debug spanning-tree all', which generates much more output and is even more CPU-intensive.

Mistake 3: Not using 'terminal monitor' before debugging over a remote session, so debug messages are not displayed.

debug spanning-tree events vs show spanning-tree

Both commands relate to Spanning Tree Protocol, but they serve different purposes: debug spanning-tree events monitors real-time STP state transitions and topology changes, while show spanning-tree provides a static snapshot of the current STP state and configuration. They are often confused because debugging STP events generates output that resembles the dynamic information shown by the show command.

Aspectdebug spanning-tree eventsshow spanning-tree
ScopeEvents (state transitions, topology changes only)Full STP state and configuration for all or a specific VLAN
Impact on deviceHigh CPU usage; must be used with cautionNo significant CPU impact
Data typeReal-time, continuous outputStatic snapshot at the moment of execution
PersistenceStops on reload or with 'no debug'One-time output, no persistence
Typical useTroubleshooting STP convergence issuesVerifying root bridge, port roles, and topology

Use debug spanning-tree events when you need to monitor real-time STP state changes during convergence issues or after topology changes.

Use show spanning-tree when you need to verify the current STP configuration, root bridge, and port roles for a VLAN.

Platform Notes

In IOS-XE (e.g., Catalyst 9000 series), the `debug spanning-tree events` command is available with similar syntax and output, but the output format may include additional details like VLAN ID in a different position or timestamps with milliseconds. For example, IOS-XE output might look like: 'STP: [VLAN0001] Port Gi1/0/2 transitioned to Forwarding'. The command works identically in IOS-XE privileged EXEC mode.

In NX-OS (e.g., Nexus 9000), the equivalent command is `debug spanning-tree events` as well, but the output is more verbose and includes event IDs. NX-OS also supports `debug spanning-tree all` for comprehensive debugging. Note that NX-OS uses a different STP implementation (Rapid PVST+ by default), so transitions are faster.

In IOS-XR, STP debugging is not directly supported because IOS-XR typically operates at Layer 3; however, for Layer 2 services, the command `debug l2vpn stp events` may be used. For ASA firewalls, STP debugging is not applicable as they are Layer 3 devices. Regarding IOS version differences: In older IOS 12.x, the debug output might not include VLAN IDs for PVST+; in 15.x and later, VLAN IDs are always shown.

Also, in some versions, the command `debug spanning-tree events` may require the `service internal` command to be enabled. Always check the specific platform documentation. For CCNA/CCNP candidates, practicing on real or simulated equipment (e.g., Packet Tracer, EVE-NG) is recommended to become familiar with the output variations.

Related Commands

show spanning-tree

Displays the Spanning Tree Protocol (STP) state and configuration for all VLANs or a specific VLAN, used to verify root bridge, port roles, and STP topology.

show spanning-tree vlan [vlan-id]

Displays Spanning Tree Protocol (STP) information for a specific VLAN, including root bridge, port roles, and port states, used to verify STP topology and troubleshoot loops.

Practice for the CCNA 200-301

Test your knowledge with practice questions covering all CCNA 200-301 exam domains.

Practice CCNA 200-301 Questions