Fix ERR_PNPM_FETCH_404 and npx install errors in DSH plugin

DSH plugin installs failing with ERR_PNPM_FETCH_404 or a broken npx @deepseek-ai/dsh have two distinct root causes: an npm mirror that has not synced the newest package (the 404 comes from the mirror, not from your command), and the node-pty native dependency shipping no prebuilt binary (on Linux it must be compiled locally). Switching to the official registry fixes the first; adding a compile toolchain and retrying fixes the second.

DSH plugin install errors: ERR_PNPM_FETCH_404 and npx failures

Error one: ERR_PNPM_FETCH_404. pnpm gets HTTP 404 while fetching a package from your configured npm registry, prints the ERR_PNPM_FETCH_404 code and aborts the install. It is one of the most reported install errors on the dshbase troubleshooting page (source):

1. You run dsh plugin add <package> (or any pnpm install of a freshly released package);
2. pnpm requests it from your current mirror (for example a regional mirror);
3. The mirror does not have that version yet, returns 404, and pnpm exits with ERR_PNPM_FETCH_404;
4. Key judgment: the 404 belongs to the mirror repository, not your network or a typo — search the same package on npmjs.com; if the official registry has it, the mirror is simply lagging.

Error two: npx install failure. npx @deepseek-ai/dsh fails while installing, with the stack pointing at node-pty. node-pty is the native module behind the dsh built-in terminal (the official repo lists it in pnpm-workspace.yaml as an allow-built native dependency, source). On Linux it ships no prebuilt binary, so the compiler must run at install time:

1. Run npx @deepseek-ai/dsh --version;
2. After the package fetch, the install stalls at the node-pty compile step;
3. The error contains gyp / node-gyp / make keywords, or the install simply fails;
4. After this step fails the dsh command is never produced — this is not a mirror problem, it is a toolchain problem, so treat it separately.

Why DSH plugin installs fail: mirror lag and missing prebuilt binaries

The two errors have unrelated root causes: ERR_PNPM_FETCH_404 is mirror sync lag (the freshly published package is not on the mirror yet), while npx install failures come from node-pty lacking prebuilt binaries (Linux compiles it on site). In detail:

1. Mirror lag: npm mirrors are copies of the official registry.npmjs.org and sync with a delay. A package published minutes or hours earlier may not exist on the mirror yet, so pnpm gets a 404 (source). dsh and its dependencies release frequently, making this time window easy to hit.
2. No prebuilt binary: node-pty ships prebuilt artifacts for some platforms only; on Linux it depends on the local build-essential (GCC/make) and python3 toolchain to compile, and fails when those are missing or Node is too old (source).
3. The two problems stack: when the mirror lags, switch the registry; when the toolchain is missing, add compilers — do not swap the actions. Switching registries will not fix a compile failure, and adding compilers will not fix a mirror 404.

Fix DSH plugin installs: official registry, pinned mirror, or local build

Match the fix to the error: ERR_PNPM_FETCH_404 → official registry; npx install failure → toolchain plus pinned registry; both fail → build locally or install globally. Step by step:

1. Check the current registry to see whether you are on a mirror:

   bash

   npm config get registry
   

   https://registry.npmjs.org/ means the official registry; anything else is a mirror — note it down, then temporarily try the official one.

2. Confirm who is actually 404ing — query the latest version against the official registry to see whether the package is published at all:

   bash

   npm view <package> version --registry=https://registry.npmjs.org
   

   A version number means the package exists and the mirror is simply lagging; a 404 here means the package may be unpublished or the name is wrong — search npmjs.com to double-check.

3. Retry with the official registry (fixes ERR_PNPM_FETCH_404) — append --registry to the install command:

   bash

   dsh plugin --profile web add <package> --registry=https://registry.npmjs.org
   

   The environment-variable form works too:

   bash

   npm_config_registry=https://registry.npmjs.org dsh plugin add <package>
   

   Expected: pnpm moves into a normal dependency fetch instead of failing with ERR_PNPM_FETCH_404 right away.

4. Install the compile toolchain (fixes npx failures). On Debian/Ubuntu:

   bash

   sudo apt install build-essential python3
   

   A clean install with no errors is enough; also confirm Node is an LTS release (node --version should print v20.x or newer).

5. Retry npx with the official registry:

   bash

   npx @deepseek-ai/dsh --registry=https://registry.npmjs.org
   

   Expected: the install reaches the download/compile stage instead of dying on node-pty. Mirrors usually catch up within hours, after which you can switch back.

6. Local build as the fallback: if compilation still fails, install globally to avoid npx re-fetching and recompiling every time:

   bash

   npm install -g @deepseek-ai/dsh
   

   Verify with dsh --version — a version number means the install succeeded.

How to verify a DeepSeek Harness install succeeded: version, plugin list, and Web UI

Installed does not mean usable — verify DeepSeek Harness and the DSH plugin with three checks: the CLI version, the plugin list, and a working Web UI. In order:

1. Check the CLI version:

   bash

   dsh --version
   

   A version number means the CLI works; command not found means the global install directory is off PATH — revisit step 6 of the fix section and confirm the install path.

2. Check the plugin list (confirms the DSH plugin is registered in the current profile):

   bash

   dsh plugin --profile web list
   

   The package you just installed appears → the plugin is in. An empty list or an error means retracing the registry/toolchain steps above.

3. Check the Web UI:

   bash

   dsh web
   

   When the terminal prints dsh web: http://127.0.0.1:3080, open http://127.0.0.1:3080 — a page that loads normally means the whole chain works.

4. Optionally prune the pnpm store: stale metadata from the earlier 404 can linger in the local cache; cleaning it makes the next install cleaner:

   bash

   pnpm store prune
   

   No output or a completion message is normal.

Notes: DSH plugin — tell mirror lag from toolchain issues first

1. For ERR_PNPM_FETCH_404, suspect mirror lag first and try --registry=https://registry.npmjs.org once — do not rewrite the package name.
2. For npx failures, read the stack: gyp / make keywords point to the compile toolchain, not the network.
3. A mirror is a copy, the official registry is the source — when checking, use the official one; if it has the package, the mirror is just unsynced.
4. After installing, head to Settings → Plugin Market for official ecosystem plugins — the DSH Plugin Hub store supports visual browsing and one-click installs, which is more reliable than hand-typed dsh plugin add.
5. See install error troubleshooting for other install issues.

Sources: dshbase troubleshooting, DeepSeek Harness pnpm-workspace.yaml, @deepseek-ai/dsh on npm