Firmware, Driver, and Operating-System Alignment | NVIDIA ConnectX NICs Triage Guide

Use this section when any of the following applies:

The issue started after a change to the firmware, driver, DOCA-Host, a DOCA SDK component, the operating system, BIOS, or the platform image.
Nodes in the same environment behave differently.
You cannot confirm that the deployed software stack is supported.

Use this section after you confirm that the adapter is visible and that PCIe and the physical link are healthy.

Quick Decision

What you see	Do this next
The issue started after a change.	Preserve the current state, and compare the exact change with the last known-good state.
Affected and healthy nodes have different versions or configurations.	Compare the complete stack with the approved platform baseline.
The issue persists with an approved, consistent stack.	Refer to InfiniBand Fabric Triage, RoCE Transport Triage, RDMA, Application, and NCCL Workload Triage, or Performance, Topology, and GPUDirect Triage.
A firmware update left the adapter unavailable.	Do not retry the update. Refer to the Adapter Absent or Unstable , and follow a documented recovery procedure for the platform. Otherwise, contact NVIDIA Support.

Establish the Software Baseline

Use the host bundle as the starting inventory. Compare these items with the approved baseline for the platform:

Adapter model, firmware version, and configuration
Driver package, version, and loaded driver
DOCA-Host release, and the version of each DOCA SDK component that the affected workload uses
Operating system and kernel
BIOS, baseboard management controller (BMC) firmware, and platform image, where relevant
Fabric-management software, switch software, and workload stack, if they changed around the time of the incident

Record where the approved baseline comes from, such as a release note or compatibility matrix. Matching version numbers do not confirm compatibility on their own.

Hosts with DOCA-Host

Before you treat the issue as a generic NIC problem, confirm that the DOCA-Host release is compatible with the NIC firmware and host driver stack. Use the documentation for the installed DOCA release:

DOCA Release Notes: supported configurations and known issues
DOCA Compatibility Policy
DOCA-Host Installation and Upgrade: installation, upgrade, and kernel requirements
DOCA Profiles: if the release uses profiles, confirm which profile is installed

DOCA diagnostic tools, such as DOCA Telemetry, can provide more evidence when they support the device and the failure. To troubleshoot a specific DOCA SDK component, see that component's DOCA documentation.

Compare Good and Bad States

For a regression, compare good-state and bad-state evidence for the following:

Exact change sequence, and any activation or reboot performed
Firmware, driver, kernel, and platform-image versions
DOCA-Host release, and DOCA SDK component versions and configuration, where applicable
Adapter configuration and port settings
Host events during driver load, reset, or activation
Whether a healthy node uses the same stack

Change one layer at a time so you can see whether the symptom follows a version, configuration, host, or workload.

Recovery and Rollback

Use only a documented recovery or rollback procedure for the platform and component. Not every DOCA release or component has a customer rollback procedure. If you cannot find one, contact NVIDIA Support before you change anything.

Before you change the stack, follow these steps:

Preserve the current host bundle and incident logs.
Record the target version and the reason for the change.
Confirm the activation and reboot requirements for the platform.
After the change, check adapter visibility, PCIe state, port state, and workload behavior.

If activation fails or the adapter disappears, stop and preserve evidence. Repeated update attempts make the original failure harder to diagnose.

Escalation Criteria

Contact NVIDIA Enterprise Support or your OEM/reseller support provider, as specified in your support agreement, when any of the following conditions applies:

The deployed combination is approved, but the issue still reproduces.
In a controlled comparison, the issue follows a specific firmware, driver, DOCA-Host, DOCA SDK component, or operating system change.
Firmware activation fails, or the adapter is unavailable after an approved update.
A platform dependency or compatibility matrix is missing or conflicts with the deployed stack.

Attachments

Current host bundle
Known-good comparison, if available
Source of the approved baseline
Exact change and activation history
Host logs around the incident
Validation results after the change

For the full escalation package, see Escalation Package and Handoff.

Last updated: October 08, 2026