Inspect, search, diagnose, and run qualified recipes with approval
| Symptom | Cause | Fix |
|---|---|---|
system inspect reports restricted or unknown actions | Untrusted or unknown release identity, missing GB300 10.3 compute capability, or an observed power-budget violation | Run .dgx-station/bin/dgx-assist system inspect and read the compatibility profile, capabilities, and restrictions. With --json, inspect data.compatibility and data.rejection_reasons. Do not bypass qualification or rely on product-name strings alone — a different build is not automatically compatible |
system inspect on a DGX Station under WSL2 reports Compatibility: WSL2, Action scope: BLOCKED, and the WSL2_GUEST reason | A WSL2 guest does not expose the bare-metal /etc/dgx-release marker, so no release profile can be matched and mutating capabilities stay off | This is expected. Use system inspect and diagnose for read-only evidence in WSL2. Run platform, MIG, and recipe workflows from the bare-metal DGX OS host. If the host is not WSL2 and still shows UNKNOWN, see the next rows |
system inspect reports UNQUALIFIED_RELEASE on a host whose software build matches | The release identity is matched as a whole: DGX_SWBUILD_VERSION, DGX_SWBUILD_DATE, and DGX_PRETTY_NAME together. A matching version and build carrying a different release name — for example NVIDIA DGX Server instead of NVIDIA DGX GB300WS — is not a recognized profile | Compare all three trusted fields against the Step 6 table. system inspect prints them under Release marker as Software version, Build date, and Release name; with --json they are in data.release_marker.trusted. Qualified recipe execution stays blocked until the full identity matches a published profile, because the shipped validation evidence names the exact identity it was qualified on. Do not edit /etc/dgx-release to force a match |
| Software 1.0 profile blocks MIG mutation and platform fixes | Expected behavior: the Software 1.0 profile is capability-scoped to guidance, diagnostics, read-only MIG inspection, and explicitly validated recipes | No action. Qualified recipe execution still works; MIG mutation and platform fixes require a profile that enables them |
| No recipe resolves for your model | The bundled v1 catalog has one runnable Software 1.0 smoke model, Qwen/Qwen2.5-Coder-1.5B-Instruct; larger candidates are deliberately non-runnable | Run .dgx-station/bin/dgx-assist recipe models and catalog status to list exact IDs. Other stable reasons: experimental lifecycle, missing LaunchSpec, mutable model or image references, stale recipe hash, expired evidence, wrong release or hardware, ambiguity, or a hard preflight conflict. No error path substitutes a different model |
playbook search returns nothing, with retrieval_trace.abstained=true | Query terms did not overlap the pinned content | Narrow the query using hardware-specific terms from the Development Guide. Do not invent a command to fill the abstention |
playbook status reports a missing or corrupt index | Damaged bundled search index | Run .dgx-station/bin/dgx-assist diagnose run, then diagnose fix --report-id REPORT --finding content.playbook.index --dry-run. Approve the fix before repeating it with --yes |
| Mixed-coherency GPU ordering looks wrong in a container | Containers do not automatically inherit host device exposure or ordinals from /etc/mixed-coherency-gpu-select/env | Inspect compatibility.capabilities first and report observed NVML addressing modes and UUIDs. Check the ordering service only when mixed_coherency_service is true. Pass explicit UUIDs; never assume nvidia-smi index 0 or 1 is the GB300 CUDA ordinal. See the mixed-coherency guide |
| A superseded bring-up passage says one CUDA context cannot use both GPUs | Bring-up content that predates the current Development Guide | Do not follow that guidance on a qualified Software 2.0 profile. The signed retrieval snapshot excludes that passage and records the current Development Guide as the superseding source. Software 2.0 can access ATS and HMM devices; do not import that behavior into Software 1.0 |
A power check fails or vsloshd is missing | dynamic_power_sloshing is not enabled on this profile, or a real budget violation was observed | When the capability is true, report the vsloshd service and mode. On Software 1.0 its absence is not a fault. Report observed caps and violations; never attempt an ad hoc power-cap fix. See the power-sloshing guide |
| vLLM tuning advice seems too generic | The request lacked an exact model and workload shape | Name the model and give ISL, generated-output distribution, target concurrency, TTFT/inter-token-latency/throughput goals, and repeated-prefix rate, then run playbook search "gpu_memory_utilization KV cache preemption" or playbook search "prefix caching chunked prefill concurrency". Do not maximize gpu_memory_utilization blindly, treat CPU memory as HBM-equivalent, promise concurrency from ISL alone, or claim a prefix-cache speedup for decode-heavy workloads |
| Preflight reports a port or GPU conflict | Another listener or GPU client owns the resource | Resolve the conflict yourself — dgx-assist never stops, kills, or takes over an unknown resource. Create a fresh resolution afterwards if any input changed |
recipe stop leaves the service running | The graceful SIGTERM timeout expired; dgx-assist does not implicitly send SIGKILL | The receipt reports a degraded stop and leaves the resource for explicit operator review. Stop it manually after confirming what it is |
| A MIG plan is rejected as stale | Clients, mode, instances, installed profiles, release identity, or the driver changed after planning | Run mig inspect and mig profiles, then create a new plan. Do not replay or edit the old commands |
| Skills are not discovered by the agent | Incomplete skill folder, wrong directory, or a harness without native skill support | Verify the native path contains the full folder and the exact uppercase filename — .claude/skills/dgx-station/SKILL.md, .agents/skills/…, .gemini/skills/…, or .cursor/skills/… — then restart the agent in that project. Upgrade a harness that lacks native skill support rather than transforming the bundle |
install.sh status reports MODIFIED files | You edited a managed file after installation | Expected and safe: the installer preserves a modified managed file during update and uninstall. Review it manually, or delete it and re-run install to restore the shipped version |
Install fails with unmanaged skill collision or unmanaged CLI collision | A same-name file exists that the installer does not own | The installer never overwrites unmanaged files. Move or delete the existing file, then re-run install |
| Install fails partway with an OS error | A write failed mid-installation | The installer records a recovery manifest covering the files that landed. Re-run install to finish, or uninstall to remove them |
install-cli --scope user refuses to write | ~/.local/bin/dgx-assist already exists or is a symlink | Remove or rename the existing destination, then re-run. The installer refuses to replace a symlink destination or an existing user CLI |
| Context file changes look unexpected | Only the delimited NVIDIA block is managed | Unrelated content is never touched, and the original file is backed up under .dgx-station/backups/ before the first managed edit. Restore from that backup if needed |
For latest known issues, see the documentation linked under Resources for your hardware platform.