Doca Version

DOCA version handling — capabilities, version compatibility, errors, observability, safety

Where to start: Pick the H2 anchor that matches your question (detection sources / four-way match / NGC / per-library overlay / errors / safety) and read that section end-to-end. The tables in each section are the load-bearing content; the prose is interpretation.

Read this file when the loader sent you here from SKILL.md. For the how of executing each pattern, jump to TASKS.md. For the JSON schemas that helper tools emit (so the agent can prefer the structured one-shot over the manual chain), see doca-structured-tools-contract/SKILL.md.

Pattern overview

Every version-handling question this skill teaches resolves into one of FIVE patterns. The patterns are CLASSES — they apply across every DOCA release, every library, and every host kind.

Two cross-cutting rules that apply to every pattern above:

• Never invent a version, never quote "latest". Always derive the version from one of the sources in ## Capabilities and modes; never trust agent memory and never copy a version string from a public docs URL without confirming it against the user's installed sources.

• The headers win over the docs. The C headers under the install tree's include directory (resolved via pkg-config --variable=includedir doca-common) are the authoritative statement of which symbols exist on this release. A public docs page that mentions a symbol absent from the headers is wrong for this install — the docs describe a release; the headers are the release.

Capabilities and modes

The canonical source-of-truth table for DOCA version detection. Every version question the agent answers must derive its version string from one of these sources; if two sources disagree, the install is partial and the answer routes to ## Error taxonomy before any other diagnosis continues.

Discovery shortcut. When the host has a structured-tools helper installed (per doca-structured-tools-contract/SKILL.md#doca-env---json-schema), doca-env --json returns all five sources in one JSON object with a version.consistent boolean that pre-computes the four-way match. Prefer this when present; fall back to the chain above when not.

Version compatibility

The four-way match rule is the central constraint DOCA version handling exists to enforce:

All of (a) pkg-config --modversion doca-common, (b) cat /opt/mellanox/doca/applications/VERSION, (c) doca_caps --version, and (on BlueField hosts) (d) the BFB-image version MUST match within a release. Any disagreement means the install is partial; the fix is to reinstall consistently, NOT a code change.

Absent source vs. disagreeing source — distinct partial-install shapes. A source returning No such file or directory or command not found is NOT the same failure as two sources returning different values. Treat absence as a partial-install signal (one or more DOCA host-packages was not installed alongside doca-common), record which sources are absent in the captured triple, and continue with the remaining sources to pin down which component is missing — do NOT route an absent-source case to a full reinstall when doca-setup can perform a targeted package installation. The canonical partial-install pattern on a host with doca-common installed is:

Confirm package vocabulary against the host BEFORE prescribing. DOCA package naming has been refactored across releases — on DOCA 3.3 the legacy doca-applications and doca-tools meta-packages no longer exist (applications/VERSION ships inside doca-samples; the tools are granular per-binary: doca-caps, doca-bench, doca-pcc-counters, doca-flow-tune, doca-comm-channel-admin, …). Before quoting an apt install line at the user, the agent MUST run apt-cache policy <pkg> (or apt-cache search ^doca-) on the target host to confirm the package name exists in that host's configured DOCA repo. A prescribed package name from this table that returns Unable to locate package is itself a finding to report — not silently ignored.

Binaries are not on $PATH by default. Per-tool binaries installed by packages like doca-caps land under /opt/mellanox/doca/tools/ (e.g. /opt/mellanox/doca/tools/doca_caps), NOT under /usr/bin/. command -v doca_caps and a bare doca_caps --version will both return "not found" on a freshly- installed DOCA 3.3 host even when the package IS installed. Probe with the absolute path (/opt/mellanox/doca/tools/doca_caps --version) or extend PATH (export PATH=/opt/mellanox/doca/tools:$PATH) before declaring the binary absent. Cross-check with dpkg -L doca-caps | grep doca_caps to confirm where the package actually placed the binary on this DOCA release.

The cross-version mixing trap (last row) is the single most common cause of “the program built but does nothing on the wire” reports for first-time DOCA users, which is why this rule sits at the top of the version skill.

Apt-repo and OS-matrix preconditions

Before quoting any apt install / apt upgrade line at the user — whether to fix a partial install, jump from one DOCA release to the next, or align host to BFB — the agent MUST clear two preconditions that are independent of the four-source chain itself. Skipping either turns a "should work" recommendation into a recoverable-but-painful failure on the user's box.

1. Apt repository pinning + apt-cache policy <pkg> precheck. latest channels and stale local repo files are the two ways an apparently-correct apt install line resolves to the wrong release on a user's host. The agent must:

   • Prefer the explicit DOCA-release-pinned repo URL form (https://linux.mellanox.com/public/repo/doca/<X.Y.Z>/<distro>/<arch>/) over the latest alias for any controlled upgrade — latest is for fresh installs, not for landing on a known target release.

   • Recommend the user disable / remove stale earlier-release repo files (e.g. a leftover DOCA 2.x doca.sources while installing 3.x); a host with both pinned can resolve to either.

   • Run apt-cache policy <pkg> for every package about to be installed BEFORE the install line is quoted. If Candidate: is (none) or Installed: (none) with no Candidate:, the package name does not exist in any configured repo on this host (legacy doca-applications / doca-tools package names are absent on DOCA 3.3+). That is a finding to surface, not a line to ignore.

2. Host OS support-matrix gate. Every DOCA release publishes a Supported Operating Systems table; a host whose OS family is listed but whose minor / point release is outside the supported sub-range (the documented case: Ubuntu 24.04.x where x ≤ 3 per DOCA 3.3's matrix, on a host running 24.04.4; DOCA 3.5 lists 24.04.x for x ≤ 4 and 22.04.x for x ≤ 5, and adds Ubuntu 26.04) is a stop-and-ask, NOT silent acceptance. The packages may install cleanly and the userspace may even pass the four-source coherence check — and then a downstream kernel-module / DKMS / OFED step quietly fails in a way that takes hours to triangulate to "you are off-matrix." The agent's required move:

   • Read the target release's Supported Operating Systems table from docs.nvidia.com/doca/sdk/<release>-release-notes/... (for DOCA 3.5 the table is on the General Support page: https://docs.nvidia.com/doca/archive/3-5-0/general-support) (route via doca-public-knowledge-map/SKILL.md).

   • Compare against the user's actual lsb_release -a / uname -r.

   • If the OS family is unsupported → refuse (this is the verification-contract ## step 1 — preconditions failure mode).

   • If the OS family is supported but the point release is outside the documented sub-range → SURFACE the gap to the user verbatim ("your Ubuntu 24.04.4 is outside the DOCA 3.3 supported sub-range of 24.04.x for x ≤ 3 per the release notes"; for DOCA 3.5 quote 24.04.x for x ≤ 4 or 22.04.x for x ≤ 5), name the documented sub-range, and ask the user to either downgrade the point release into the supported window or to accept the off-matrix risk explicitly before proceeding.

These two preconditions sit ABOVE the four-source chain, not inside it: they protect against failures that the four-source chain cannot detect because they occur before any DOCA package gets to claim a version at all.

Authoritative upstream source for compatibility windows. NVIDIA's own statement of which release pairings are intended to work — quarterly GA cadence, October LTS designation (3-year support, 7-update LTS train), the semver X.Y.Z scheme, the three compatibility types (source / binary / behavioral), and the two compatibility directions (backward / forward) — is the DOCA Compatibility Policy. Cite this URL whenever the user asks “is my LTS still supported”, “what does the version string mean”, or any host ↔ DPU compatibility question. This skill detects what is installed; the Compatibility Policy describes which installs NVIDIA intends to work together.

NGC container semantics. When the user reached an install via the public NGC DOCA container (per doca-setup ## no-install (doca-setup/TASKS.md#no-install) Path 0), the four-way match is of the container: the headers, *.so, samples, and doca_caps are all built and shipped together at the container tag the user pulled. Mixing artifacts built inside the container with a *.so from a different DOCA install on the host is the same partial-install trap as case (a) ≠ (c) on a non-container host. Before declaring a container coherent, record pkg-config --variable=prefix doca-common and LD_LIBRARY_PATH, then run ldd <built-binary> inside the container. Every resolved DOCA library must come from the container's observed DOCA prefix; a host-mounted or other-prefix DOCA *.so is contamination and fails the coherence gate.

Cross-version *.so loading is not supported. A program built against version X must run against runtime version X. The doca_<library>_cap_* query family is the right way to ask “is this capability supported” without resorting to header probes or build-time guards.

Error taxonomy

Version-related errors the agent should recognize and disambiguate before continuing to a library- or program-level diagnosis. For the cross-library DOCA_ERROR_* taxonomy itself, see doca-programming-guide CAPABILITIES.md ## Error taxonomy (doca-programming-guide/CAPABILITIES.md#error-taxonomy); the rows below are the version-level upstream causes that bubble up as those errors.

Observability

The version handling observability surface is the set of commands that read version state, and the structured-tools fields that report it in one shot. There is no DOCA "version counter" — the visibility comes from probing the sources in ## Capabilities and modes.

Three primary signals the agent should reach for:

1. The four-way match status. Either version.consistent from doca-env --json (preferred) or the agent computing it itself from the manual chain. The single most informative one-line answer to “is my install consistent”.

2. The version-matrix lookup result. Either a row in version-matrix.json (preferred) or the manual fallback of fetching the per-library docs page and extracting the “available since” prose (per doca-structured-tools-contract ## version-matrix.json schema (doca-structured-tools-contract/SKILL.md#schemas)). No populated version-matrix.json is provided with the bundle or with DOCA, so in practice the agent falls back to fetching the “available since” prose from the per-library docs via doca-public-knowledge-map/SKILL.md. That fallback is correct (the answer comes from NVIDIA's freshest source) but slower than a local lookup. The agent never treats the missing data file as a "no answer" — it walks the manual fallback. If the docs fetch fails, report the attempted URL and failure, do not guess the minimum version, and route to the matching library skill for manual verification.

3. The capability-query result. The per-library doca_<library>_cap_* API answers “is this supported on this device + this version” at runtime. The version-matrix is the promise; the capability query is the reality. When they disagree, the capability query wins.

For the env-side observability primitives (LD_LIBRARY_PATH, PKG_CONFIG_PATH, ldconfig -p) see doca-setup CAPABILITIES.md ## Observability (doca-setup/CAPABILITIES.md#observability). For the cross-cutting debug-time observability (--sdk-log-level, the doca-<lib>-trace flavor, DOCA_LOG_LEVEL) see doca-debug CAPABILITIES.md ## Observability (doca-debug/CAPABILITIES.md#observability).

Safety policy

Version handling's safety surface is anti-hallucination. The single most common bundle failure mode without this skill is the agent quoting a version from memory or from a public-docs URL without confirming it against the user's installed sources. The rules below exist to prevent that.

• Never quote "latest". "Latest" is not a version. The user's installed version is the version. If the user actually does not know what they have installed, route to TASKS.md ## configure before answering any other question.

• Never copy a version from a URL. A URL like docs.nvidia.com/doca/sdk/.../v3.3/... describes what was current when the page was published, not what the user has.

• Never assume the four-way match. Always verify the user's sources agree before answering a “is X supported” question. The cost of asking the user to run two commands is much smaller than the cost of telling them a feature exists when their install pre-dates it.

• Never recommend a workaround for a partial install. For an absent source, route to doca-setup for targeted package installation. When observed source values disagree, route to doca-setup for a consistent reinstall. Pinning LD_LIBRARY_PATH to a different *.so, manually copying a header, or any other workaround perpetuates the bug and makes the next failure harder to diagnose.

The per-library overlay pattern. Every library / service / tool skill in the bundle has a ## Version compatibility section in its own CAPABILITIES.md. To stop those sections from drifting from this skill, the bundle convention is:

A library / service / tool skill's ## Version compatibility section MUST be 3-5 lines that (a) cross-link to this skill for the four-way match rule + detection chain + NGC semantics, and (b) add at most one library-specific overlay rule (e.g. “the DOCA Comch library was renamed from DOCA Comm Channel in DOCA 2.5; the pkg-config module name is doca-comch on 2.5+”). It MUST NOT redefine the four-way match rule or restate the detection chain.

The bundle's conformance checks flag repeated /opt/mellanox/doca references in a library skill's CAPABILITIES.md; if you find yourself accumulating warnings on a new skill's ## Version compatibility, you are duplicating instead of cross-linking.

Deferred topic boundaries

This skill scopes itself to DOCA version handling. Adjacent topics the agent will get asked but should route elsewhere:

• Installing DOCA, choosing packages, post-install verification. Owned by doca-setup/SKILL.md. This skill assumes something is installed somewhere; the version question is what was installed and is it consistent.

• Per-library capability availability (which symbols exist in Flow at version X). The version-matrix lookup procedure in TASKS.md ## test is generic; the per-library interpretation belongs in the matching library skill's ## Capabilities and modes.

• Cross-library DOCA_ERROR_* taxonomy. Owned by doca-programming-guide CAPABILITIES.md ## Error taxonomy (doca-programming-guide/CAPABILITIES.md#error-taxonomy). This skill's ## Error taxonomy is the version-level upstream causes that bubble up as those errors.

• General debug ladder (install / version / build / link / runtime / program / driver). Owned by doca-debug ## debug (doca-debug/TASKS.md#debug). This skill owns layer 2 (version mismatch); the other layers redirect.

• Routing to public docs and the on-disk install layout. Owned by doca-public-knowledge-map/SKILL.md. This skill cites the Compatibility Policy URL once via that map; it does not duplicate the routing.