/doca-debug

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 <doca-feedback@nvidia.com>
  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