Diagnose in layers, not by guessing
Most reported failures come from one of five layers. Checking them in order avoids reinstalling a plugin when the real problem is the Node version or a stale profile cache.
| Layer | Typical symptom | First thing to check |
|---|---|---|
| Runtime | The CLI will not start at all | Node and package-manager versions |
| Profile | The plugin installs but never appears | The composed config for the profile you actually ran |
| Bundle | Install succeeds, load fails | Whether the bundle patch exists and resolves |
| Duplication | Services register twice or conflict | Duplicate Cordis copies in the dependency tree |
| Interface | CLI works, Web UI does not | Whether the web profile and its port are actually serving |
1. Confirm the runtime before anything else
A mismatched Node version or a partially installed package manager produces errors that look like plugin bugs. Establish the runtime first so later results mean something.
node -v && npm -v && npx -y @deepseek-ai/dsh --version2. Dump the composed profile
DSH composes a profile from ordered bundle patches plus your own overrides. If the plugin is missing from the dumped tree, the problem is composition, not the plugin code.
dsh --profile web --dump-config3. Re-check the bundle manifest
A bundle whose package.json names a patch that is not published in the package will install cleanly and then fail to load. Confirm the manifest and the patch file agree.
https://dsh-plugin.net/check/<owner>/<repo>4. Look for duplicated Cordis
Two copies of the Cordis runtime in one dependency tree break service identity, so plugins appear to register but cannot see each other. This is common after mixing package managers or linking a local checkout.
npm ls cordis5. Isolate with a clean profile
If the plugin works in a fresh profile, the fault is in your existing composition — an override, an ordering conflict, or a stale cache — rather than the plugin itself.
- Create an empty profile and add only the failing plugin.
- Clear the profile cache before re-testing.
- Reintroduce your other bundles one at a time.
- Record the first bundle that reproduces the failure.
What to include in a bug report
A report with these fields is usually actionable on the first reply, which matters while DSH remains in developer preview.
- DSH version, operating system, Node and package-manager versions.
- The exact install command and the profile name.
- The plugin version or commit SHA.
- The relevant part of the dumped config.
- Whether a clean profile reproduces the failure.
DeepSeek Harness is in developer preview. Recheck official documentation and plugin evidence when the host version changes.
Official sources
These primary sources were used to verify the technical details in this guide.