FAQ & Troubleshooting - DeepSeek Harness

When something goes wrong, first figure out which step you're stuck on: launch, configuration, or running. Here are the common issues and how to debug them.

Launch

Command not found / version mismatch

Make sure Node.js is installed (^20.19 || >=22); building from source also requires pnpm
Quick start uses npx @deepseek-ai/dsh web; from source, use pnpm dsh web
If npx has a stale cache, try npx @deepseek-ai/dsh@latest web

npx @deepseek-ai/dsh web hangs / shows no output

First tell whether it is actually stuck: the first npx run downloads the @deepseek-ai/dsh package from npm before starting; on a slow network the terminal just sits at the download stage and looks like a hang — give it a moment, or test npm connectivity with npm view @deepseek-ai/dsh version
Switch the npm registry: if npm is unreachable or slow, run npm config set registry https://registry.npmmirror.com, then retry npx @deepseek-ai/dsh web
Check your Node version: node -v must satisfy ^20.19 || >=22; older versions can fail silently with no output
Bypass a stale cache: use npx @deepseek-ai/dsh@latest web, or clear the npx/npm cache and retry
Check whether it actually started: open the default address http://127.0.0.1:3080 in a browser; if the port is taken or an instance is already running, see "Port in use / wrong address" below
Corporate proxy / firewall: blocking npm downloads looks the same as a hang — configure the proxy or switch networks and retry
If there is still no output at all, stop it with Ctrl+C and run again; if it still hangs, bring the run mode, Node version, and terminal output to GitHub Discussions

Port in use / wrong address

The default address is http://127.0.0.1:3080; trust the address the command actually prints
If the port is taken, change it per the CLI help or free the port

Configuration

Model not responding

Confirm you entered your DeepSeek API key under Settings → Models and saved
Model routing works immediately, no restart needed; if it still fails, check the key and any other provider settings

Session input disabled

This means no workspace is selected: click Select workspace, add the directory where you launched dsh, and select it

Running

An action asks for approval

When an action needs approval under the current permission policy, the Web UI asks first — that's expected; approve or reject as needed

Compatibility changes

DeepSeek Harness is a developer preview (v0.1) iterating rapidly — there will be compatibility-breaking changes
After upgrades, if interfaces differ, follow the official README and docs

Where to get help

GitHub Discussions: usage questions, bug reports, feature suggestions → discussions
Official docs: architecture, development, and guides → docs
Community chat: Discord / WeCom group — see the official README

For bug reports

Include: how you run it (npx / source), your Node.js version, and the full error message — the more complete, the faster the fix.