Modular QoS Configuration Guide for Cisco 8000 Series Routers, Cisco IOS XR Release

PDF

Modular QoS Configuration Guide for Cisco 8000 Series Routers, Cisco IOS XR Release

Stuck VOQ isolation

Updated: September 11, 2026

Want to summarize with AI?

Log in

Describes the diagnostic capability that isolates a detected stuck Virtual Output Queue condition to the ingress or egress network processing unit and line card and reports the affected side through operational show commands.

Stuck Virtual Output Queue (VOQ) isolation is a Modular QoS diagnostic capability that

  • determines whether a detected stuck VOQ condition originates on the ingress or egress network processing unit (NPU) line card

  • replaces the debug-shell workflow previously required to isolate the affected ingress or egress NPU line cards, and

  • displays the affected interface and VOQ information, diagnostic status, and recommended action.

A stuck VOQ has a queue depth that remains unchanged even when no traffic is present. The VOQ watchdog detects the condition and reports it in an Cisco IOS XR system message. Stuck VOQ isolation determines whether the detected condition is associated with the ingress or egress NPU line card.

Table 1. Feature History Table

Feature Name

Release Information

Feature Description

Identify the source of a stuck VOQ

Release 26.3.1

Introduced in this release on: Modular Systems (8800 [LC ASIC: Q100, Q200])

You can now determine whether a detected stuck VOQ condition originates on the ingress or egress NPU line card. Previously, isolating the affected side required debug-shell commands. The new operational commands display the affected VOQ and interface information, diagnostic status, and recommended action.

The feature introduces these changes:

CLI:

  • show controllers npu stuck-voq status

  • show controllers npu stuck-voq isolation

  • show controllers npu stuck-voq isolation detail

YANG Data Model:

  • Cisco-IOS-XR-8000-platforms-npu-stuck-voq-status-oper.yang

*This feature is supported on:

  • 8800-LC-36FH

  • 8800-LC-48H

  • 88-LC0-36FH

  • 88-LC0-36FH-M

  • 88-LC0-34H14FH

Limitations for stuck VOQ isolation

The stuck VOQ isolation feature does not support Internal VOQs.

Isolate a stuck VOQ to an ingress or egress line card

Use this task to isolate a detected stuck-VOQ condition to the affected ingress or egress NPU line card and identify the line card that requires replacement.

Before you begin

Complete these prerequisites before you begin:

  • Enable the VOQ watchdog feature.

  • Disable automatic card shutdown for stuck-VOQ detection so that you can complete the isolation workflow.

The default behavior shuts down the card when a stuck VOQ is detected.

Procedure

  1. Enable VOQ watchdog detection and disable automatic card shutdown.

    Example:

    Router(config)# hw-module voq-watchdog feature enable
Router(config)# hw-module voq-watchdog cardshut disable

  2. Monitor the output of the show logging CLI command for any Cisco IOS XR message that reports a stuck VOQ.

    When the router detects a stuck VOQ, it displays the system message for the ingress line card.

  3. Check the stuck-VOQ status.

    Example:

    Router# show controllers npu stuck-voq status
Mon Aug 24 14:09:12.022 UTC

Location : 0/0/CPU0
====================
------------------------
Stuck voq info on Ingress LC/NPU:

No Stuck VOQ entries found
------------------------
------------------------

------------------------

Stuck port/tc info on Egress LC/NPU:

+----------------+------+------------------+--------------+------------------+------------------+--------------+---------------------------+---------------------------+
|                |      | Dest port info   |              | Ingress LC stuck voq detection info                                                                       |
+----------------+------+------------------+--------------+------------------+------------------+--------------+---------------------------+---------------------------+
| Intf-name      | (hex)| Slot/NPU/Slice   | VOQ Base     | Slot/NPU/Slice   | Stuck VOQ/VSC    | Detect Count | First Timestamp           | Last Timestamp            |
+----------------+------+------------------+--------------+------------------+------------------+--------------+---------------------------+---------------------------+
| Hu0/0/0/8      | 0160 | 0/0/0            | 832          | 2/0/0            | 832/1440         | 3640         | Fri Aug 21 19:07:44.942 UTC | Mon Aug 24 14:08:53.487 UTC |
+----------------+------+------------------+--------------+------------------+-------------+--------------+---------------------------+---------------------------+

Location : 0/2/CPU0
====================
------------------------
Stuck voq info on Ingress LC/NPU:

+----------------+------+------------------+--------------+------------------+------------------+--------------+---------------------------+---------------------------+
|                |      | Dest port info   |              | Ingress LC stuck voq detection info                                                                       |
+----------------+------+------------------+--------------+------------------+------------------+--------------+---------------------------+---------------------------+
| Intf-name      | (hex)| Slot/NPU/Slice   | VOQ Base     | Slot/NPU/Slice   | Stuck VOQ/VSC    | Detect Count | First Timestamp           | Last Timestamp            |
+----------------+------+------------------+--------------+------------------+------------------+--------------+---------------------------+---------------------------+
| Hu0/0/0/8      | 0160 | 0/0/0            | 832          | 2/0/0            | 832/1440         | 3640         | Fri Aug 21 19:07:44.934 UTC | Mon Aug 24 14:08:53.486 UTC |
+----------------+------+------------------+--------------+------------------+-------------+--------------+---------------------------+---------------------------+

------------------------
Stuck port/tc info on Egress LC/NPU:

No Stuck VOQ entries found
------------------------

    This command is nonintrusive and can be run while the router is still in service.

    On a modular system, the command retrieves information from all line cards for detected stuck VOQs.

  4. Take the router offline.

    Take the router out of service before you perform the isolation operation.

  5. Isolate the stuck VOQ to the ingress or egress NPU line card.

    Example:

    Router# show controllers npu stuck-voq isolation
Mon Aug 24 14:09:18.012 UTC

Location : 0/0/CPU0
====================
------------------------
Stuck voq info on Ingress LC/NPU:

No Stuck VOQ entries found
------------------------
------------------------

------------------------

Stuck port/tc info on Egress LC/NPU:

+----------------+------+------------------+--------------+------------------+------------------+--------------+---------------------------+---------------------------+---------------------+
|                |      | Dest port info   |              | Ingress LC stuck voq detection info                                                                       |                     |
+----------------+------+------------------+--------------+------------------+------------------+--------------+---------------------------+---------------------------+---------------------+
| Intf-name      | (hex)| Slot/NPU/Slice   | VOQ Base     | Slot/NPU/Slice   | Stuck VOQ/VSC    | Detect Count | First Timestamp           | Last Timestamp            | Status              |
+----------------+------+------------------+--------------+------------------+------------------+--------------+---------------------------+---------------------------+---------------------+
| Hu0/0/0/8      | 0160 | 0/0/0            | 832          | 2/0/0            | 832/1440         | 3640         | Fri Aug 21 19:07:44.942 UTC | Mon Aug 24 14:08:53.487 UTC | RMA location 0/0/CPU0 |
+----------------+------+------------------+--------------+------------------+-------------+--------------+---------------------------+---------------------------+---------------------+

Location : 0/2/CPU0
====================
------------------------

Stuck voq info on Ingress LC/NPU:

+----------------+------+------------------+--------------+------------------+------------------+--------------+---------------------------+---------------------------+---------------------+
|                |      | Dest port info   |              | Ingress LC stuck voq detection info                                                                       |                     |
+----------------+------+------------------+--------------+------------------+------------------+--------------+---------------------------+---------------------------+---------------------+
| Intf-name      | (hex)| Slot/NPU/Slice   | VOQ Base     | Slot/NPU/Slice   | Stuck VOQ/VSC    | Detect Count | First Timestamp           | Last Timestamp            | Status              |
+----------------+------+------------------+--------------+------------------+------------------+--------------+---------------------------+---------------------------+---------------------+
| Hu0/0/0/8      | 0160 | 0/0/0            | 832          | 2/0/0            | 832/1440         | 3640         | Fri Aug 21 19:07:44.934 UTC | Mon Aug 24 14:08:53.486 UTC | GOOD                |
+----------------+------+------------------+--------------+------------------+-------------+--------------+---------------------------+---------------------------+---------------------+

------------------------
Stuck port/tc info on Egress LC/NPU:

No Stuck VOQ entries found
------------------------

    Check the Status column to identify the line card associated with the fault.

    • GOOD indicates that the line card is not identified for replacement.

    • RMA location <slot> identifies the line card at the specified location for replacement.

    For additional diagnostic information, use the following command:

    Router# show controllers npu stuck-voq isolation detail
Mon Aug 24 14:09:21.203 UTC

Location : 0/0/CPU0
====================
------------------------
Stuck voq info on Ingress LC/NPU:

No Stuck VOQ entries found
------------------------
------------------------

------------------------

Stuck port/tc info on Egress LC/NPU:

+----------------+------+------------------+--------------+------------------+------------------+--------------+---------------------------+---------------------------+--------+----------+--------+---------------------+
|                |      | Dest port info   |              | Ingress LC stuck voq detection info                                                                      |        |          |        |                     |
+----------------+------+------------------+--------------+------------------+------------------+--------------+---------------------------+---------------------------+--------+----------+--------+---------------------+
| Intf-name      | (hex)| Slot/NPU/Slice   | VOQ Base     | Slot/NPU/Slice   | Stuck VOQ/VSC    | Detect Count | First Timestamp           | Last Timestamp            | Credit | StaticGo | Grant  | Status              |
|                |      |                  |              |                  |                  |              |                           |                           | Deficit|          | Count  |                     |
+----------------+------+------------------+--------------+------------------+------------------+--------------+---------------------------+---------------------------+--------+----------+--------+---------------------+
| Hu0/0/0/8      | 0160 | 0/0/0            | 832          | 2/0/0            | 832/1440         | 3640         | Fri Aug 21 19:07:44.942 UTC | Mon Aug 24 14:08:53.487 UTC | 2095104 | 0        | 0      | RMA location 0/0/CPU0 |
+----------------+------+------------------+--------------+------------------+------------------+--------------+---------------------------+---------------------------+--------+----------+--------+---------------------+

Location : 0/2/CPU0
====================
------------------------

Stuck voq info on Ingress LC/NPU:

+----------------+------+------------------+--------------+------------------+------------------+--------------+---------------------------+---------------------------+-----------+---------------------+
|                |      | Dest port info   |              | Ingress LC stuck voq detection info                                                                       |           |                     |
+----------------+------+------------------+--------------+------------------+------------------+--------------+---------------------------+---------------------------+-----------+---------------------+
| Intf-name      | (hex)| Slot/NPU/Slice   | VOQ Base     | Slot/NPU/Slice   | Stuck VOQ/VSC    | Detect Count | First Timestamp           | Last Timestamp            | VOQ Empty | Status              |
+----------------+------+------------------+--------------+------------------+------------------+--------------+---------------------------+---------------------------+-----------+---------------------+
| Hu0/0/0/8      | 0160 | 0/0/0            | 832          | 2/0/0            | 832/1440         | 3640         | Fri Aug 21 19:07:44.934 UTC | Mon Aug 24 14:08:53.486 UTC | Yes       | GOOD                |
+----------------+------+------------------+--------------+------------------+-------------+--------------+---------------------------+---------------------------+-----------+---------------------+

------------------------
Stuck port/tc info on Egress LC/NPU:

No Stuck VOQ entries found
------------------------

    The detailed output additionally displays:

    • VOQ Empty for the ingress NPU line card.

    • Credit Deficit, StaticGo, and Grant Count for the egress NPU line card.

    Use detail when additional debugging information is required before replacing the line card.

  6. Shut down and replace the line card identified for RMA.

    Shut down the line card reported as RMA location <slot> and replace the line card.

  7. Reload the chassis after replacing the line card.

    Example:

    Router# reload location all

  8. Take the router online.

    After the chassis reload completes with the replaced line card, return the router to service.

The stuck-VOQ condition is isolated to the affected ingress or egress NPU line card. The line card identified for replacement is replaced before the router is returned to service.