NCCL Topology Linter
The failures that burn the most GPU-hours are the ones that were guaranteed before step 0: a NIC on the wrong side of the root complex, ACS silently killing GPUDirect, anNCCL_IB_HCAthat matches nothing. Paste your node's topology bundle and get every one of them flagged — with the exact fix — before the job gang-schedules.
nvidia-smi topo -m env | egrep "NCCL|FI_|UCX" ibstat ip -br addr ulimit -l sudo lspci -vvv | grep -B1 ACSCtl
Frequently asked questions
What does the topology linter check?
Five layers: (1) GPU↔GPU fabric — NVLink islands vs pairs crossing the CPU interconnect; (2) GPU↔NIC affinity — ranks whose nearest NIC sits behind the CPU root complex, where GPUDirect RDMA silently disables itself; (3) PCIe ACS — bridges with Access Control Services enabled, which redirect P2P through the root complex and break or throttle GDR; (4) NCCL environment — NCCL_IB_HCA validated against your actual HCAs and port states, NCCL_SOCKET_IFNAME against real interfaces, plus typo detection across 60+ documented NCCL variables; (5) limits — RLIMIT_MEMLOCK ceilings that make ibv_reg_mr fail under load.
Does my data leave my machine?
No. The linter runs entirely in your browser as compiled JavaScript. The paste box contents are never transmitted. Scale+ customers can run the identical engine server-side via POST /api/preflight/topology for CI gates.
How is this different from denpex preflight-cluster?
denpex preflight-cluster (the agent command) validates the runtime: rendezvous, ring bandwidth, port sanity, GPU/driver uniformity, ulimits, clock skew. This linter validates the configuration underneath: it reads the actual PCIe/NVLink/NIC topology and checks your NCCL settings against it. Run both — the agent before every gang-schedule, the linter whenever the fabric, drivers, or NCCL env change.
Why do PCIe ACS settings matter for NCCL?
With ACS enabled on a bridge, every peer-to-peer transaction is forced up to the root complex for access validation. GPU↔GPU P2P bandwidth collapses and GPUDirect RDMA breaks or throttles, which NCCL surfaces as mysterious slow all-reduce or 'peer access not supported' errors. On bare metal the fix is disabling ACS in BIOS or via setpci; on virtualized hosts it may be required for isolation, in which case you disable P2P deliberately instead of debugging ghosts.
Gate your CI on it
The same engine runs server-side at POST /api/preflight/topology (Scale+), and the Denpex GitHub Action / GitLab template can block a merge on a blocker-level finding.