Troubleshooting

Common DeepSeek Harness install and runtime issues, with fixes grounded in the official CLI reference and docs (verified 2026-08-13). Fixes are commands you can copy — nothing here is guessed.

Installation failures

“Command not found” after npx

npx downloads the package on demand but does not install the dsh binary globally. Re-run npx @deepseek-ai/dsh web (npx resolves it each time), or install globally if you want a persistent dsh command:

npx cache is stale

The preview iterates fast; a cached copy can look outdated or fail to match docs. Clear the npx cache and retry:

Network / registry issues (China mainland)

• Switch npm to a mirror: npm config set registry https://registry.npmmirror.com (same for pnpm).
• If a proxy is required, ensure HTTP_PROXY/HTTPS_PROXY are set for the shell that runs npx.

Node.js version too old

DSH requires Node.js ≥ 18 (LTS recommended). Check and upgrade:

Boot & port issues

Port 3080 already in use

The Web UI serves at http://127.0.0.1:3080 by default. If another process holds it, the web app accepts a --port flag — the launcher passes app arguments through after its own flags:

The web profile also accepts repeatable --trusted-host flags.

“Profile not found” error

Only web and headless auto-initialize from shipped templates on first use. Any other profile name fails loud with a hint:

Windows

• PowerShell execution policy — if a script is blocked, run Set-ExecutionPolicy -Scope CurrentUser RemoteSigned (or use cmd).
• Spaces in paths — quote paths with spaces: dsh --patch "C:\My Plugins\cordis.yml".
• Windows launcher — a community dsh-launcher-windows exists; treat it as external (no dsh manifest, not verified by dsh.so).

Config & plugin debugging

Inspect the composed tree without booting

See exactly what your machine would load — every row, and the file that supplied it:

--dump-default-config prints only the bundle layers; --dump-config adds the profile's cordis.patch.yml, the home-level $DSH_HOME/cordis.patch.yml, and --patch overlays. Unmatched patch targets are reported on stderr — a common cause of “my plugin didn't load”.

Plugin didn't load

• Absolute path — a local --patch row referencing a source file needs an absolute path; relative paths resolve against the profile directory, not your cwd.
• Name resolution — a bundle row references the package by name; if the install was a git checkout without a prepare build, the lib/ output may be missing (see Plugin Development).
• Config replaced, not merged — a later patch replaces the whole config value of a row; restate every key, not just the changed one.

Headless task exits with code 1

dsh --profile headless "run the tests" prints the final assistant text and exits 0 for completed, else 1. Exit 1 means the task did not reach a completed state — inspect the session log or re-run with more specific instructions.

Where to get help

• Official GitHub Discussions — the project's canonical support channel (issues are not used).
• Official Discord community.
• dsh.so Plugin Registry for finding plugins, and the Changelog for version changes.