DeepSeek Harness Plugin Troubleshooting: dsh Install Errors, cordis.patch.yml Conflicts & Profile Fixes (2026)

When to use this page

Use this page when something between "I found a plugin" and "the plugin is running" has gone wrong: a failed dsh plugin add, an odd pnpm-workspace allowlist failure in a monorepo, a cordis.patch.yml that ignores you, or a profile that loads the wrong plugin set. Each section below follows the same shape — symptom, then cause, then the commands that fix it.

If you have not reached the install step yet, start with Installing Plugins Safely. If you are not sure which config layer you are editing, read the Configuration Guide first.

One rule before everything else: restart dsh after every config change. The plugin tree is assembled at startup by the Cordis container, so half of all "nothing happened" tickets are config edits that were never restarted.

1. Plugin not found during install

Symptom. dsh plugin add dsh-some-tool fails with a resolution error, or succeeds but the plugin never appears anywhere.

Cause. The CLI resolves packages from the npm registry by exact name. The usual culprits: a typo in the package name, a missing @scope/ prefix, a plugin that is only distributed through GitHub (so it has no npm entry), and a --profile <name> flag that does not match the profile you start later — the entry lands in a profile you never launch.

Fix.

1. Verify the exact published name: npm view dsh-some-tool. The plugin's detail page and repository README show the working install command — community installs are documented by the plugin itself.
2. If the plugin is GitHub-only, install from source with a branch or tag pin: dsh plugin add github:owner/repo#main.
3. Match the flag to the launch: if you installed with dsh plugin --profile web add <package>, start it with dsh --profile web — not a bare dsh.
4. During local development, link the folder directly: dsh plugin add ./path/to/my-dsh-plugin.

2. Install hangs or fails: pnpm workspace allowlist

Symptom. Inside a pnpm monorepo, installing a plugin hangs, or fails with an error mentioning pnpm-workspace allowlist, module not found, or ESM & CJS resolution problems — especially when the plugin comes from a git or local build.

Cause. pnpm enforces strict dependency boundaries. A plugin installed from GitHub effectively becomes part of the workspace, and if its package is not declared within the workspace boundary, pnpm will not link it — so Node cannot resolve the plugin or its dependencies at runtime.

Fix.

1. Declare the package inside the boundary: add it to the workspace root package.json dependencies (or the allowlist/catalog in pnpm-workspace.yaml), then run pnpm install from the workspace root.
2. Re-add the plugin and restart: dsh plugin add <package>, then start dsh again so the rebuilt tree loads.
3. Prefer the npm registry version when one exists — published packages carry their dependencies with them and skip the boundary problem entirely.
4. Confirm the runtime: node -v should report 20.0.0 or higher.

3. cordis.patch.yml conflicts (override order)

Symptom. Two plugins overlap — two sidebar panels, two OCR engines, two implementations of the same service — and one plugin's settings are silently ignored. dsh may report a Profile patch collision / Override order issue.

Cause. Patches are the top override layer above bundles and profiles, and later entries win. When two entries register the same service or UI panel, declaration order decides. A duplicated key or an indentation slip in the YAML can also silently rewrite an entry.

Fix.

1. Open the file you actually use: cat ~/.dsh/profiles/<name>/cordis.patch.yml, or <project-root>/.dsh/cordis.patch.yml when you are inside a workspace.
2. Reorder: move the plugin that should win to the bottom of the plugins: list — it overrides earlier entries.
3. Or keep both but disarm the conflict: set enabled: false on one plugin's entry.
4. Cleanest long-term fix: move the conflicting plugins into separate profiles and launch with dsh --profile <name>.
5. Validate the YAML before restarting — one bad indent changes what an entry means: yq eval . cordis.patch.yml.

4. dsh bundle format errors

Symptom. dsh starts, but the plugin set looks nothing like the documentation, or a config file copied from somewhere keeps triggering collision errors instead of loading.

Cause. The three config layers have different jobs: a bundle is an official plugin set shipped with the harness, a profile is your named assembly of bundles and plugins, and a patch surgically overrides a single plugin entry. A cordis.patch.yml that re-declares an entire bundle — dozens of entries, plus settings that belong in the profile layer — mixes formats, and those overrides start colliding with what the bundle already provides.

Fix.

1. Keep patches surgical — one plugin per entry, enabled and options only:

# ~/.dsh/profiles/default/cordis.patch.yml
plugins:
  dsh-vision-toolkit:
    enabled: true
    options:
      ocrEngine: 'default'

2. If you want a whole set of plugins at once, configure the set at the profile level instead of pasting every entry into a patch.
3. Delete the duplicated entries, save, and restart dsh. The plugin's tools or panels should now load with no collision messages.

5. Profile not taking effect

Symptom. You edited a cordis.patch.yml, restarted, and nothing changed — or a plugin you installed for a specific profile is nowhere to be found.

Cause. One of three classic mistakes: editing the wrong file (there are two locations, and the workspace file overrides the global one), launching with a different profile name than the folder you edited, or never restarting at all.

Fix.

1. Check both locations: ls ~/.dsh/profiles/*/cordis.patch.yml 2>/dev/null and ls .dsh/cordis.patch.yml 2>/dev/null from the project root.
2. Remember precedence: <project-root>/.dsh/cordis.patch.yml wins over ~/.dsh/profiles/<name>/cordis.patch.yml when both exist.
3. Match the flag to the folder: editing ~/.dsh/profiles/web/cordis.patch.yml means launching with dsh --profile web — not dsh, and not dsh --profile headless.
4. Restart and verify: dsh --profile web, then check that the plugin's tools or panels are present. Still missing? Go to the next section.

6. Plugin installed but not loading (failed to register)

Symptom. The install succeeded and the config looks right, but at startup dsh reports Plugin failed to register / Lifecycle timeout — or the plugin silently never loads.

Cause. Usually the runtime is too old (Node.js below 20), dependencies are missing (git installs need their own build step), declaration order collides with another plugin, or the entry was left enabled: false. A related failure mode is the sandbox: dsh runs read-only by default, so a plugin that needs disk or network access can be blocked at load time with Permission denied / Sandbox security policy violation.

Fix.

1. Check the runtime: node -v — upgrade to 20.0.0 or higher (Node 22 LTS recommended).
2. Source installs need their build: from the plugin directory run pnpm install && pnpm build, then restart.
3. Reinstall cleanly: dsh plugin remove <package>, confirm the entry in cordis.patch.yml, then dsh plugin add <package> again.
4. Confirm the entry is active: dsh plugin add writes enabled: true; if you hand-edited the YAML, make sure it is still there.
5. If the error mentions the sandbox and the plugin is verified, launch with dsh --sandbox workspace-write (see Safety Guidelines).
6. Installed from the dsh-market Web UI? Check Settings → Plugin Market for the plugin's status — the backend applies config and hot-reloads, so a failed state shows up there.

Still stuck?

• Installing Plugins Safely — the install methods, profiles and CLI cheat sheet
• Configuration Guide — bundles, profiles and patches: which layer are you actually editing?
• Submit a plugin — if a plugin's README disagrees with what happens on your machine, open an issue on its repository with your exact dsh --profile command and the error text; maintainers fix discrepancies fastest that way.