Fix DeepSeek Harness Deploy Errors: Deps, PATH & Builds

When a DeepSeek Harness deploy errors, classify it first: ERR_MODULE_NOT_FOUND and Cannot find package point to dependency resolution, dsh not found points to PATH, and ERR_PNPM_IGNORED_BUILDS points to build scripts. Match the error in the quick table below, then follow the corresponding item.

Overview: classify the deploy error first

DeepSeek Harness deploy errors almost all happen during dependency installation, and they fall into three classes: dependency resolution, command PATH, and build scripts. Based on a real walkthrough of deploy errors, the typical chain is: npx @deepseek-ai/dsh web fails to start → npm global or local install reports Cannot find package in bulk → switching to pnpm with --shamefully-hoist fixes resolution → ERR_PNPM_IGNORED_BUILDS blocks native modules → approve-builds allows the build scripts → npx dsh web finally starts on port 3080. Each error in this chain is one independent fix:

The official install command is npx @deepseek-ai/dsh web (source). Below, each class is one section, each error is one item written as error / cause / fix.

Class 1: Dependency resolution errors (ERR_MODULE_NOT_FOUND, Cannot find package)

This is the biggest bucket. The root cause is that @deepseek-ai/dsh is a monorepo: its plugin system references many standalone packages through peer dependencies, and npm's flat install strategy cannot resolve them — you must switch to pnpm.

ERR_MODULE_NOT_FOUND

• Error: running npx @deepseek-ai/dsh web (source) fails with ERR_MODULE_NOT_FOUND: Cannot find package '@deepseek-ai/cordis-plugin-group'.
• Cause: the npx temp cache resolves dependencies incompletely and misses many peer dependencies.
• Fix: do not keep retrying npx — the problem is not the network, it is that npx's cache cannot pull in all peer deps. Clear the cache and reinstall dependencies locally with the pnpm flow in the next item.

Cannot find package (bulk missing)

• Error: after a local npm install @deepseek-ai/dsh --legacy-peer-deps, startup reports a flood of Cannot find package '@deepseek-ai/dsh-xxx' (e.g. dsh-timeout, dsh-atomic-write), covering 50+ plugin packages.
• Cause: @deepseek-ai/dsh is a monorepo whose plugin system references many packages via peer dependencies; npm's flat install cannot resolve this structure. --legacy-peer-deps only skips peer conflict checks — it does not actually install peer dependencies, so packages are still missing.
• Fix: remove the old dependencies and lockfile, then install with pnpm — pnpm handles workspaces and peer dependencies properly, --shamefully-hoist emulates npm's flat structure, and --config.dedupe-peer-dependents=false turns off deduplication (source):
  bash

  # 1. Create a package.json in an empty directory (skip if you have one)
  npm init -y
  
  # 2. Clean the old dependencies (Windows: del package-lock.json + rmdir /s /q node_modules)
  rm -rf node_modules package-lock.json
  
  # 3. Install dsh with pnpm (the key flags)
  npx pnpm add @deepseek-ai/dsh --shamefully-hoist --config.dedupe-peer-dependents=false
  

  If pnpm itself is not found, always use npx pnpm instead. This step downloads 500+ packages and takes a while.

Class 2: Command & PATH errors (dsh: command not found)

Dependencies are in place but the command will not start — usually a PATH problem. This class has two faces: the command does not exist, or it exists but packages are missing.

dsh: command not found

• Error: after npm install -g @deepseek-ai/dsh, running dsh web says the command is not found.
• Cause: the npm global bin directory is not on PATH, so the shell cannot find the dsh executable.
• Fix:
  1. Find the global bin directory with npm prefix -g and add it to PATH (commonly %AppData%\npm on Windows, /usr/local/bin on macOS/Linux).
  2. Easier: skip global install. Install locally with pnpm and always start with npx dsh web — npx picks up dsh from the local node_modules/.bin.

The endless missing-package loop

• Error: after fixing PATH, dsh web still reports missing packages like cordis-plugin-loader, and fixing one reveals another.
• Cause: npm does not install peer dependencies automatically, and DSH depends on dozens of internal sub-packages, so manual installs never catch up.
• Fix: stop patching packages one by one. This is a dependency resolution problem — go back to the pnpm flow in Class 1 and reinstall once to pull in all peer dependencies.

Class 3: Build-script & network errors (ERR_PNPM_IGNORED_BUILDS, error 23)

After switching to pnpm, dependency resolution passes, but pnpm's security policy ignores build scripts for native modules by default, and an unstable network spams timeout warnings. Each has one standard fix.

ERR_PNPM_IGNORED_BUILDS

• Error: after pnpm install completes, it reports [ERR_PNPM_IGNORED_BUILDS] Ignored build scripts: ... Run "pnpm approve-builds" to pick which dependencies should be allowed to run scripts. (source).
• Cause: pnpm's security policy does not run dependency build scripts by default, so native modules like node-pty and koffi never compile, and the app crashes at runtime.
• Fix: approve the build scripts and reinstall (source):
  bash

  # 1. Approve build scripts: press a to select all, then confirm Yes
  npx pnpm approve-builds
  
  # 2. Reinstall to run those scripts
  npx pnpm install --shamefully-hoist --config.dedupe-peer-dependents=false
  

  This time node-pty, koffi, and other native modules compile cleanly.

Network timeout error 23

• Error: the download spams error (23) network timeout warnings.
• Cause: an unstable network times out on some package downloads.
• Fix: nothing to do — pnpm retries automatically and eventually downloads everything (source). If it keeps failing after many retries, switch the npm registry to a mirror and run npx pnpm install again.

General debugging flow

Run any deploy error through this order — most problems are solved by the pnpm step.

1. Classify the error → match it in the quick table: dependency resolution, PATH, or build scripts.
2. Dependency resolution errors → clear node_modules and the lockfile, reinstall with pnpm and --shamefully-hoist (the key step).
3. Command not found → check PATH with npm prefix -g, or install locally and start with npx dsh.
4. Build scripts ignored → npx pnpm approve-builds, select all, then pnpm install.
5. Verify startup → npx dsh web; the terminal shows http://localhost:3080 and you are done.
6. Plugin support → once the deploy is up, if installing DSH plugins errors, use the DSH Plugin Hub plugin center for one-click installs and avoid git-source builds that ship no artifacts.

Notes

1. Node.js 18 or newer — older versions fail to resolve dependency declarations.
2. Always clean node_modules and the lockfile before switching package managers; never mix installs.
3. --legacy-peer-deps only skips peer checks — it does not save you from a monorepo's missing packages, so do not rely on it.
4. If pnpm is not found, use npx pnpm; they are interchangeable.
5. Global install is optional — local pnpm install plus npx dsh web is cleaner.
6. error (23) retries automatically, so do not interrupt the install.
7. The web UI starts at http://localhost:3080; if the port is taken, find the occupying process first.

Source: DeepSeek Harness documentation - Quickstart, DeepSeek Harness README, dsh CLI README, pnpm approve-builds, pnpm settings