Skip to main content
skill CX Codex

doca-debug — Claude Code skill: DOCA debugging

doca-debug finds the failing DOCA layer, from installation and linking to runtime and drivers. Use it for unresolved symbols, DOCAERROR results, silent tools, and crashes.

Apache-2.0 162 installs ★ 4,106 updated 2026-10-23

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add NVIDIA/skills --skill doca-debug -a claude-code
Open on GitHub

What doca-debug does

This skill maps a DOCA failure to the relevant layer: installation, version, build, link, runtime, program, or driver. It covers cases such as undefined reference to doca, a DOCAERROR result, silent services and tools, stack traces, valgrind output, and core dumps.

It explains the available logging controls, including --sdk-log-level, DOCA_LOG_LEVEL, and the doca-{lib}-trace flavor. It also describes what to capture for a Developer Forum post and accounts for container-debug limits. The validation steps require a live DOCA installation at /opt/mellanox/doca, so those checks cannot run without the SDK there.

Library-specific Flow pipe, RDMA QP, and Comch stats debugging is routed elsewhere. The same applies to pkg-config or hugepages environment symptoms, DOCA_ERROR_* lifecycle interpretation, performance work, and incident response.

What it helps with

  • identify the failing DOCA layer
  • diagnose an undefined reference to doca linker error
  • turn on detailed logs for a DOCA library or tool
  • prepare reproducible state for a Developer Forum post
  • separate a container constraint from a runtime failure

Example prompts for the agent

  • Classify undefined reference to doca_flow_init by layer and tell me which observations to collect first.
  • Show how to use --sdk-log-level, DOCA_LOG_LEVEL, or doca-{lib}-trace when my DOCA program is silent.
  • Tell me what to capture for a reproducible Developer Forum question after doca_caps returns nothing.

How to install doca-debug

1Skills CLI (Vercel)

npx skills add NVIDIA/skills --skill doca-debug -a claude-code

2Manually: put the files in place

~/.claude/skills/doca-debug/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/doca-debug/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about doca-debug

How do I install doca-debug in Claude Code?

Run npx skills add NVIDIA/skills --skill doca-debug -a claude-code, then check ~/.claude/skills/doca-debug/SKILL.md.

What does doca-debug do?

It investigates DOCA failures across the installation, version, build, link, runtime, program, and driver layers. It also covers logging and evidence collection for forum reports.

Does doca-debug require DOCA to be installed?

The skill can be read without DOCA, but its validation checks need a live installation at /opt/mellanox/doca.

Source text

SKILL.md · Apache-2.0
---
license: Apache-2.0
name: doca-debug
description: >
  Use this skill when the user is debugging any DOCA symptom — a build
  that won't compile, a link step that can't resolve a doca_* symbol, a
  runtime call returning DOCA_ERROR_*, a silent service or tool, or a
  stack trace / valgrind / core dump — and needs the layered ladder
  (install → version → build → link → runtime → program → driver),
  verbosity controls (--sdk-log-level, DOCA_LOG_LEVEL, the
  doca-{lib}-trace flavor), container-debug constraints, or how to
  capture state for a Developer Forum post. Trigger even when the user
  does not say "DOCA debug" — implicit phrasings include "undefined
  reference to doca_*", "how do I get more logs", "packets aren't
  reaching the wire", "doca_caps returned nothing", or "hugepages empty
  in the container". Refuse and route elsewhere for library-specific
  debug (Flow pipe trace, RDMA QP, Comch stats), env-class pkg-config or
  hugepages symptoms, the DOCA_ERROR_* taxonomy and lifecycle
  interpretation, and performance or incident-response work — those
  belong to other skills.
metadata:
  author: NVIDIA <[email protected]>
  kind: library
  doca_version: "3.5"
  tags:
    - doca
    - debug
compatibility: >
  No DOCA install required to read this skill (it is an overlay loaded
  against any DOCA artifact skill); the validation steps within DO
  require a live DOCA install at /opt/mellanox/doca.
---

# DOCA debug

## Examples

- **"My DOCA build / link / runtime failed — which layer is
  it?"** — this is in scope. Walk the layered ladder; do not
  jump to library-internal debug first.
- **"How do I turn up verbosity for any DOCA library or
  tool?"** — use the log-level / trace-flavor surface, then
  capture state for a forum post.

## Instructions

An `undefined reference` is a **Link-layer symptom**, not proof of a
missing library or an application-code defect. Before recommending edits,
request these observations from the **same host/container and shell that
ran the failing build**:

- `pkg-config --modversion doca-common` and the selected library's version;
  for Flow, `pkg-config --modversion doca-flow`.
- `pkg-config --libs doca-<library>`; for Flow, `pkg-config --libs doca-flow`.
- The actual failing compiler/linker invocation from the build log and its
  full error output. `pkg-config` reports flags, not the command that failed.

**If these outputs are missing, request them and pause before prescribing a
repair.** Listing a check is not evidence that it passed. Do not append a
speculative fix, guessed `-L`/`-l` flags, predicted library filenames, or a
replacement compiler command to that capture request. Once evidence is
available, compare the original invocation with the complete observed
`pkg-config` output through the existing build system; do not hand-assemble
DOCA's version-dependent split libraries. Use `ldd` only if a relevant binary
was actually produced; a declaration in a header does not prove that a linked
shared object exports the symbol.

Follow `doca-version/TASKS.md#configure` for version coherence,
`doca-programming-guide/TASKS.md#debug` for the
environment-before-program investigation, and
`doca-public-knowledge-map/SKILL.md` for verified
install locations and public documentation. A bundle skill name is not an SDK
page slug: never construct a documentation URL from it. If no matching guide
has been verified, use the [DOCA SDK index](https://docs.nvidia.com/doca/sdk/index.html)
and say the specific page is not yet confirmed.
Then follow [TASKS.md](TASKS.md#debug) for the staged investigation; later
phases are conditional on observed results, not instructions to guess a fix.

**First reply when only a linker error is available (Flow example).**
Use this capture-only shape, adapting the library to the actual question:

> This is a link-time failure. An undefined-symbol message does not tell us
> the installed version or which build setting is wrong. From the same
> host/container and shell as the failing build, please paste these outputs:
>
> ```bash
> pkg-config --modversion doca-common
> pkg-config --modversion doca-flow
> pkg-config --libs doca-flow
> ```
>
> Also include the actual failing linker invocation, full error output and
> whether the build ran on the host or in a container. Do not change flags,
> packages or source yet. Phases 3–5 are pending this evidence; no repair has
> been selected. Once the observations are available, we can compare them,
> choose one justified correction and rerun the original build. The link
> check is successful only when that build exits cleanly without the missing
> symbols; it does not establish runtime or hardware correctness.

End that first reply at the evidence request and pending decision. Do not add
an example repair command after it, even with a disclaimer to verify it later.

**Where to start:** This skill is the canonical layered-ladder
reference both `doca-setup/SKILL.md`
and `doca-programming-guide/SKILL.md`
escalate to. If the symptom does not fit cleanly in env-class or
program-class, start at the tasks companion — the
full layered ladder lives there.

## Example questions this skill answers well

The CLASSES of debug questions this skill is built to answer, each
with one worked example.

- **"My DOCA build / link / runtime / program failed — which layer is
  it?"** — worked example: *"`ld` says `undefined reference to
  doca_flow_init` — which layer?"* Answered by the canonical layered
  ladder in the tasks companion (layer 4 = Link).
- **"How do I turn up verbosity for any DOCA library or tool?"** —
  worked example: *"My DOCA Flow program is silent — where do I get
  more log output?"* Answered by the trace-flavor / log-level surface
  in the capabilities companion
  + the run-with-verbosity workflow in
  the tasks companion.
- **"How do I capture state for a forum question or bug report?"** —
  worked example: *"I'd like to file a forum question with reproducible
  context — what should I include?"* Answered by the
  capture-a-reproducible-state workflow in
  the tasks companion.
- **"What does this DOCA tool's output mean / which tool answers
  this?"** — worked example: *"`doca_caps` returned nothing for RDMA
  — does that mean unsupported?"* Answered by the
  tool-vs-capability decision tree in
  the capabilities companion
  + cross-link to `doca-caps/SKILL.md`.
- **"I'm debugging inside the NGC container — what's
  observable?"** — worked example: *"`hugepages` is empty inside the
  container; is that a real problem or a container thing?"*
  Answered by the container-specific debug constraints in
  the capabilities companion
  + the tasks companion layer 5 (Runtime).
- **"Where do I ask for help with this?"** — worked example: *"Where
  is the customer-facing DOCA forum and what should the post
  contain?"* Answered by the Developer-Forum routing rule in
  the tasks companion plus
  `doca-public-knowledge-map/SKILL.md`.

If the symptom is purely env-class, route to
`doca-setup/SKILL.md`; if purely
program-class, route to
`doca-programming-guide/SKILL.md`.
This skill is the cross-cutting layer both call into.

## When to load this skill

Load this skill when the user is debugging anything DOCA-related — a build that won't compile, a link step that can't resolve a `doca_*` symbol, a runtime call that returns `DOCA_ERROR_*`, a packet that does not appear on the wire, a service that won't start, or a tool that returns no useful output. Concretely:

- The user reports a symptom and needs to find the layer that caused it (install / version / build / link / runtime / program).
- The user asks "how do I get more logs?" or "how do I turn up the verbosity?" for any DOCA library or tool.
- The user wants to capture state for a forum question or an internal bug report (the bundle does not own the internal-bug-report channel; it routes to the public DOCA Developer Forum).
- The user is reading a stack trace, a `valgrind` output, or a core dump from a DOCA program and wants to know where to look first.
- The user is debugging *inside* the NGC DOCA container and needs to know what is and is not observable from inside it.

Do **not** load this skill for:

- *"What is `DOCA_ERROR_BAD_STATE`?", "what error codes does DOCA return?"* — that is the cross-library *error taxonomy*, owned by `doca-programming-guide/SKILL.md`. This skill consumes that taxonomy; it does not redefine it.
- *"My `pkg-config` cannot find `doca-flow`", "hugepages are not mounted", "my representor isn't visible"* — those are env-class symptoms, owned by `doca-setup/SKILL.md`. This skill is the canonical pointer that env-class debug ladder redirects to once the symptom escalates beyond install / version / build prerequisites.
- *Library-specific debugging* (Flow pipe trace, RDMA queue-pair state, Comch channel statistics) — those live in the matching library skill (e.g. `doca-flow/SKILL.md`). This skill provides the cross-cutting debug ladder; library skills layer their library-specific debug surface on top of it.

## What this skill provides

This is a **thin loader**. The body keeps only the orientation needed to pick the right next file. The substantive debug material lives in two companion files:

- the capabilities companion — what *kinds of debug surface* DOCA exposes: the layered debug model (install / version / build / link / runtime / program), the read-only-first stance, version-availability of debug tools (e.g. `doca_caps` since DOCA 2.6.0), the cross-library error taxonomy (cross-link only — owned by `doca-programming-guide`), the observability primitives DOCA emits (`stderr` logs, `--sdk-log-level`, the `doca-<lib>-trace` build flavor, library counters), and the safety constraints on debug actions (read-only first, don't mutate install tree mid-investigation).
- the tasks companion — the actual debug workflows: `## configure` (set up env for high-verbosity debug), `## test` (capture a reproducible state), `## debug` (the canonical layered ladder, the universal entry point that every library `## debug` redirects to), and the *Where to ask for help* routing (NVIDIA DOCA Developer Forum). Three other anchors (`build`, `modify`, `run`) route to `doca-programming-guide/SKILL.md`, which owns those verbs after the env / program split.

## Loading order

1. Read this skill first to confirm the user's symptom is *cross-cutting* debug (not env-class only, not program-class only, not library-internal only).
2. **For the layered debug model, the read-only stance, the version-availability of debug tools, and the observability surface DOCA emits, see the capabilities companion.**
3. **For the canonical layered debug ladder and the *capture-and-report* workflow, see the tasks companion.** The `build`, `modify`, and `run` anchors in the tasks companion are stubs that route to `doca-programming-guide/SKILL.md`; their substance lives there.
4. If the user's symptom turns out to be env-class (install / build prerequisites), hand off to `doca-setup/SKILL.md`. If program-class, hand off to `doca-programming-guide/SKILL.md`. If library-internal, hand off to the matching library skill's `## debug` (e.g. `doca-flow/SKILL.md`).

The two companion files cross-link to each other and to `doca-public-knowledge-map/SKILL.md` whenever the right answer is *"look it up in the public docs or the installed package layout"* rather than *"debug-specific guidance"*.

## Related skills

- `doca-public-knowledge-map/SKILL.md` — public DOCA documentation routing and the on-disk layout of an installed DOCA package. This skill defers all *"where is X documented"*, *"where on disk is Y"*, and *"how do I check the installed version"* questions to the knowledge-map.
- `doca-setup/SKILL.md` — env-class debug (install / build prerequisites): `pkg-config` failures, missing hugepages, representors not visible, header-vs-runtime version mismatches. `doca-setup ## debug` is the env-class layered ladder; this skill is the cross-cutting debug ladder both env and program ladders escalate to.
- `doca-programming-guide/SKILL.md` — program-class debug (lifecycle order, `DOCA_ERROR_*` interpretation, `doca_error_get_descr()` use, the validate-before-commit rule). `doca-programming-guide ## debug` is the program-class layered ladder; this skill picks up where it leaves off when the symptom involves cross-library tooling (`gdb`, `valgrind`, container introspection, core dumps).
- Library skills (e.g. `doca-flow/SKILL.md`, `doca-dms/SKILL.md`, `doca-caps/SKILL.md`) — library-specific debug overlays. Each library's `## debug` builds on the cross-cutting ladder defined here, then adds its own counters, traces, and inspector tools.

© NVIDIA · Apache-2.0 · NVIDIA/skills

Similar skills

All skills for Agent setup: memory, context, orchestration →

From the same set312

The whole set →
nemo-relay-plugin-adaptive-tuning nemo-relay-plugin-adaptive-tuning is a Claude Code skill that configures and evaluates NeMo Relay adaptive behavior from runtime signals, including telemetry, parallelism, hints, and prompt-cache planning. CX Codex +1 178installs nemo-relay-migrate-from-flow nemo-relay-migrate-from-flow — a skill that automates code, documentation, and config migration from NeMo Flow to NeMo Relay. Handles Python, Rust, Node.js, Go, C FFI, CLI, and observability surfaces. CX Codex +1 171installs doca-bench This skill guides doca_bench runs to measure DOCA library performance on a host or BlueField Arm. Use it to check throughput or latency and record a baseline before changing a system. CX Codex +1 166installs nemo-relay-get-started The nemo-relay-get-started skill routes first-time NeMo Relay users to the right quick-start, then checks whether the initial integration actually works. CX Codex +1 163installs doca-bf3-deployment doca-bf3-deployment is a skill for day-1 BlueField-3 provisioning over classic RShim/BFB, handling BFB image push, TMFIFO setup, DPU mode selection, and recovery. CX Codex +1 159installs doca-bare-metal-deployment doca-bare-metal-deployment is a Claude Code skill for running DOCA applications on an x86 host with a BlueField NIC or on BlueField Arm without containers, and diagnosing launch failures. CX Codex +1 158installs doca-bf4-deployment doca-bf4-deployment — a skill for BlueField-4 DPU day-1 deployment via BMC: ISO installation, PLDM firmware update, Grace Ubuntu provisioning. Each mutating step requires explicit confirmation and is governed by rollback policy. CX Codex +1 155installs doca-common The doca-common skill covers DOCA’s shared building blocks for BlueField DPU and ConnectX NIC work, from device discovery to buffers, task completion, and logs. CX Codex +1 155installs

Project sponsors

Companies that keep this analytics open