DeepSeek Harness Plugin Install Errors, Fixed

Most dsh plugin add failures fall into three buckets: pnpm isn't reachable, a GitHub-sourced plugin needs a build permission you haven't granted, or a plugin's build didn't produce what dsh expects to load. This guide walks through each, with the exact symptom to look for and the fix.

Why plugin installs fail in predictable ways

dsh plugin --profile <name> <args...> forwards everything after the profile flag straight to pnpm, executed inside that profile's directory. Because of that, almost every install failure is really a pnpm failure wearing a dsh command — which is good news, because it means the errors are consistent and well understood, not dsh-specific mysteries.

Error 1: "command not found: pnpm"

Symptom: dsh plugin --profile web add <package> fails immediately, before any package resolution starts, often with a shell-level "command not found" or similar.

Cause: dsh plugin shells out to pnpm directly. If pnpm isn't installed or isn't on your PATH, there's nothing for it to forward to.

Fix: Install pnpm and confirm it resolves from your shell (pnpm --version). If you installed dsh via a package manager that also manages pnpm through Corepack, make sure Corepack itself is enabled.

Error 2: the allowBuilds block

Symptom: A dsh plugin add github:owner/repo call fails with pnpm refusing to run a build/prepare script, and suggesting you add an allowBuilds entry.

Cause: pnpm 10 and later block prepare scripts on git dependencies by default. GitHub installs pull source, not build output — if the plugin is TypeScript without a checked-in lib/ directory, it needs that prepare script to run before dsh can load it, and pnpm won't run it without explicit permission.

Fix: Add the package to allowBuilds in the profile's pnpm-workspace.yaml:

allowBuilds:
  dsh-hello-plugin: true

Only do this for source you've reviewed or trust, and pin the install to a commit (github:owner/repo#<sha>) — this grants the package permission to run arbitrary code on your machine at install time, outside any sandbox dsh's runtime applies later. Our GitHub install guide covers this prompt end to end, and the security checklist covers what to look at before you grant it.

Error 3: "Cannot find module" after a GitHub install

Symptom: The add command itself appeared to succeed (possibly after you granted allowBuilds), but the plugin fails to load the next time you start the profile, with a module-resolution error.

Cause: Almost always one of two things — either the build step didn't actually run (check whether the package declares a prepare script in package.json at all, and whether the build permission was granted for the right package name), or the repository genuinely doesn't produce the output dsh expects (an authoring gap in the plugin, not something fixable from the install side).

Fix: Confirm the build ran by checking whether a lib/ (or whatever main points to in package.json) directory actually exists inside the installed package in node_modules. If it's missing and no prepare script exists to generate it, this plugin isn't correctly packaged for a GitHub install — look for an npm-published alternative, or check the plugin's issue/discussion tracker.

Error 4: local path installs resolving to the wrong directory

Symptom: dsh plugin --profile demo add ./hello-plugin fails with a resolution error, or — more confusingly — succeeds but installs something other than the plugin you meant.

Cause: A relative local path is resolved from wherever you ran the add command, not from the profile's own directory. If you run the command from your home directory but the plugin folder is relative to a project directory three levels down, pnpm resolves the path from where your shell currently is, not from anywhere dsh-specific.

Fix: Either cd into the directory the relative path is meant to be relative to before running add, or use an absolute path so there's no ambiguity:

dsh plugin --profile demo add /Users/you/projects/hello-plugin

This same class of mistake applies to tarball installs (dsh plugin --profile demo add ./hello-plugin-0.1.0.tgz) — the tarball path is resolved the same way.

Quick diagnosis table

Symptom	Most likely cause	Where to look
Fails before any package resolution	pnpm missing from PATH	pnpm --version in your shell
Install refuses to run a build script	allowBuilds not granted (pnpm 10+ default)	Profile's pnpm-workspace.yaml
Install succeeds, plugin fails at startup	Missing build output (lib/)	node_modules/<package> inside the profile
Install succeeds, dsh prints a warning and does nothing	Package has no dsh field in package.json	The package's own package.json — see our plugin discovery guide
A local path install can't find your plugin	Relative path resolved from the wrong directory	Local paths resolve from your current shell directory, not the profile

The one non-error worth knowing: silent no-op installs

If dsh plugin add completes without error but the plugin doesn't seem to do anything, check whether the package actually declares a dsh.bundle or dsh.profile field in its package.json. A package without that field still installs fine as a plain dependency — pnpm has no reason to fail — but dsh prints a warning and doesn't activate any configuration from it. This isn't a bug; it's how dsh distinguishes real plugins from ordinary libraries a plugin might depend on. See how to find DeepSeek Harness plugins for how to verify this before you install.

Community diagnostic tools

A handful of community-built plugins exist specifically to catch these problems before or after they happen. dsh-plugin-check runs health checks against the manifest protocol, patch format, and known build traps for already-installed plugins. dsh-doctor is a diagnostic, repair, and rollback plugin aimed at exactly this class of install problem. These are ordinary third-party dsh plugins — not part of dsh itself, and not independently verified by us — so install them with the same scrutiny covered in our security checklist before relying on them.

Confirming the fix worked

After resolving any install error, run:

dsh --profile web --dump-config

This prints the fully composed configuration, showing exactly which bundle patches are active. It's the most reliable way to confirm a plugin actually made it into the running configuration rather than just sitting in node_modules unresolved.

FAQ

Why does the same plugin install fine on npm but fail from GitHub?

npm-published plugins ship prebuilt output, so there's no build step and no allowBuilds prompt. The GitHub version of the same plugin is source code, which needs a prepare script to run — and that's exactly the step pnpm 10+ blocks by default.

Is there a way to check if a plugin will need allowBuilds before I install it?

Look at the repository's package.json for a scripts.prepare entry, and check whether the repo checks in a lib/ (or equivalent) directory. If there's a prepare script and no prebuilt output, expect the prompt.

I granted allowBuilds but the install still fails — now what?

Check the actual build error output, not just the permission prompt. A granted build can still fail on its own terms — missing build tooling, a Node version mismatch, or a genuinely broken build script in the plugin itself.

Does dsh have its own error codes for plugin installs?

No — because dsh plugin forwards to pnpm, the errors you see are pnpm's own error output. There's no separate dsh-specific error taxonomy for the install step itself.

What if none of these match my error?

These three cover the vast majority of install-time failures specifically. For broader environment and runtime issues (Node version mismatches, platform-specific bugs, session errors), see our 12-error troubleshooting guide.

Next steps

For the full picture on GitHub installs and the allowBuilds decision, read installing plugins from GitHub. For errors that show up after a plugin is running rather than during install, see DeepSeek Harness troubleshooting. And before granting build permissions to anything you haven't reviewed, walk through the plugin security checklist.