---
title: "DGX Station AI Skills and dgx-assist — Troubleshooting"
canonical: "https://build.nvidia.com/station/ai-skills/troubleshooting.md"
---

# Common issues

| 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 |
| 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 Station-specific terms. 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 [NVIDIA mixed-coherency guide](https://docs.nvidia.com/dgx/dgx-station-development-guide/coherency.html) |
| Older guidance says one CUDA context cannot use both GPUs | Superseded bring-up passage that predates the current Development Guide | Do not follow it on the qualified R610+ 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 [NVIDIA power-sloshing guide](https://docs.nvidia.com/dgx/dgx-station-development-guide/dynamic-power-sloshing.html) |
| 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 |