Troubleshoot DeepSeek Harness
Most first-run failures are environment problems, not “the model is broken”. Work through this list in order: Node version → package fetch → local port → API credentials → workspace permissions. Commands and flags still belong to the official README; this page rewrites the operator checklist so you can search and recover faster. Pair it with the Install guide and the plugin guide if add/remove is what failed.
node: command not found / engine unsupported
Official preview docs ask for Node.js ^22.19.0 or >=24.0.0. Run node -v. If the binary is missing, install LTS from nodejs.org or your OS package manager and reopen the terminal so PATH updates. nvm/fnm users must select the version in the same shell that runs npx. Old Node 18/20 may fetch a package then fail mid-install on engines.
npx is slow, 404, or stale @deepseek-ai/dsh
First run downloads many npm dependencies. Use a stable network. If a mirror is behind official npm, retry with --registry=https://registry.npmjs.org. Clear a bad npx cache if the CLI insists on an ancient rc. Confirm the package name is @deepseek-ai/dsh (not a typo’d scope).
pnpm is not recognized
Plugin add/remove often shells out to pnpm even when you started via npx. Install pnpm (for example npm install -g pnpm) and ensure its global bin is on PATH. Source installs already expect pnpm install && pnpm run build && pnpm dsh web.
Port 3080 is taken / UI never opens
The Web UI commonly binds http://127.0.0.1:3080/. If another process holds 3080, stop it or start with the port flag documented upstream (community reports use --port 8080 on dsh web). Opening 0.0.0.0 from another machine is a security decision — keep first tests on localhost. A blank page can also be a browser extension blocking local scripts; try a clean profile.
API errors after the first message
The local UI is not local inference by default: the DeepSeek route needs a platform key. Check model id, quota, and that you did not paste a key with spaces. Headless/CLI may read $DSH_HOME/.credentials.yaml (often ~/.dsh/.credentials.yaml). On Unix, overly open file modes can make the runtime refuse the credentials file — chmod 600. This site never issues keys.
Agent cannot see files / too much filesystem
Re-select the workspace root. Starting npx inside the project directory helps defaults, but you should still confirm the path in Settings. Do not point the first experiment at your entire home folder. OS permission dialogs (macOS TCC, Windows controlled folders) can silently block writes.
Plugin add failed or nothing changed
Read the plugin README for the exact dsh plugin add line (github:owner/repo vs npm name). Reload the profile after install. If Cordis cannot resolve a dependency, you will see it in the terminal that launched dsh — not always in the chat. See the plugin guide and curated cards.
Preview broke after an upgrade
Developer preview warns of breaking changes. Pin a version for eval, reread the GitHub README, and compare Trajectory logs before/after. Do not assume a blog post from last week still matches CLI flags.
If you are still stuck
Search GitHub Discussions on deepseek-ai/deepseek-harness for the exact error string. Come back to Install for OS one-liners, Community Plugins for known-good add commands, and Compare if you are deciding whether DSH is the right harness at all.
Related DeepSeek Harness paths
Re-run the install steps, check run modes if tools behave differently than expected, or read the FAQ before you change harnesses.