Troubleshooting
Diagnose install dependencies, credentials and configuration compatibility, model/network, port, workspace, permission and build errors
Work through DeepSeek Harness problems as symptom → cause → fix. Each section lists the symptom, the most likely cause and an actionable remedy. If it isn't covered here, report it to the community.
Before you start: three quick checks
Run these in order first; they rule out most cases:
- Node version:
node --versionshould meet^22.19or>=24. - Key validity: confirm the model API key works and the API endpoint is reachable.
- Network: both the first launch and model calls need network access.
Installation and dependencies
| Symptom | Cause | Fix |
|---|---|---|
pnpm install fails with missing or checksum errors | A stale or corrupted pnpm store cache | Run pnpm store prune to clear stale cache, then pnpm install again; if needed, remove node_modules and reinstall |
| Dependency download is slow or times out | Network unreachable or the npm registry is down | Check the network; if needed, switch to a reachable npm registry and retry |
| Install errors point at pnpm itself | The pnpm version is too old | Upgrade pnpm to a newer version and retry |
Plugin install is rejected with an unrun prepare script | pnpm ≥10 refuses to run git dependencies' prepare scripts until explicitly allowed | Copy the exact package key pnpm prints into that profile's pnpm-workspace.yaml (onlyBuiltDependencies); see plugins |
| Build artifacts missing or command not found | Wrong Node version | Confirm node --version meets ^22.19 or >=24; see installation |
'npx'/'node' is not recognized | Node.js is not installed, or the terminal wasn't reopened after installing | Reinstall Node.js and reopen the terminal; on Windows check the installer added Node to PATH; see installation |
First npx run hangs | It is downloading dependencies, or the network is down | Confirm network access and wait for the first download to finish |
Credentials file and version switches
plugin tree failed to load with the value for "version" ... must be a string
This is not, by itself, a Node.js 24 error. It occurs before the Web server starts: the running older credentials-local reader is treating a top-level version: 1 in .credentials.yaml as an ordinary credential and requires every top-level value to be a string. In other words, the DSH that actually ran and the credentials document use incompatible pre-release layouts.
Do not infer the active version solely from whether you typed npx or dsh. The .../node_modules/@deepseek-ai/dsh/... path in the traceback identifies the installation that was loaded. In that same Node environment, check:
npm list -g @deepseek-ai/dsh --depth=0
npm view @deepseek-ai/dsh versionDo not make version: "1" your permanent fix
An old flat-layout reader only treats the quoted version as an ordinary credential named version; if the document also has a refs: mapping, it will fail on the next wrong-typed entry. This is neither a migration to the current layout nor a fix for mixed versions.
Recommended repair: back up, then use one released version
Stop every DSH process first and back up the full harness home (normally ~/.dsh). The backup contains sessions, settings, and profiles; the later recovery moves only the credentials file and does not delete that data.
cp -a ~/.dsh ~/.dsh.bak-$(date +%Y%m%d-%H%M%S)
npm uninstall -g @deepseek-ai/dsh
npm install -g @deepseek-ai/[email protected]
npm list -g @deepseek-ai/dsh --depth=0
dsh webThe .credentials.yaml layout in 0.1.1-rc.2 is versioned. This is the smallest form for API-key references; version must be numeric, not a string:
version: 1
refs:
DEEPSEEK_API_KEY: sk-…
OPENAI_API_KEY: sk-…The current release recognizes and migrates a strict old flat credentials mapping during boot. Do not manually remove version or flatten refs after upgrading; non-API-key credentials such as OAuth can also use an additional records section. See the upstream dsh-credentials-local documentation for the authoritative layout.
It still cannot start after the upgrade, and you can re-enter the keys
Rename the old credentials file instead of deleting it, then start the Web UI and save the keys again under Settings → Models:
mv ~/.dsh/.credentials.yaml ~/.dsh/.credentials.yaml.before-$(date +%Y%m%d-%H%M%S)
chmod 700 ~/.dsh
dsh webThis starts the new version with an empty credential store; .credentials.yaml.before-… keeps the original data, while sessions, settings, profiles, and the rest of ~/.dsh remain untouched. Once the new file exists, repair a permissions error with:
chmod 600 ~/.dsh/.credentials.yamlNever run cat on this file for a support request, post a screenshot of it, or commit its API keys.
Similar startup and configuration errors at a glance
These errors usually occur before the Web server begins listening. Start with the exact file path, profile name, and plugin name in the error, and repair only the named file; do not delete the whole ~/.dsh directory because one configuration file is damaged.
| Error fragment | Usual cause | Safe response |
|---|---|---|
credentials-local: ... readable beyond its owner (mode 644) | The credentials file is readable by the group or other users | Once the path is confirmed, run chmod 600 ~/.dsh/.credentials.yaml; the directory should also be chmod 700 ~/.dsh. |
credentials-local: invalid document, must be a mapping, or is empty; remove the key instead | YAML syntax error, a non-mapping root, an empty value, or duplicate keys left by manual editing | Back up the full harness home first and never send this file's contents to anyone. You can rename only .credentials.yaml, let the Web UI write keys again, and retain the original file for rollback. |
settings-file: invalid document or must be a map of namespace sections | Broken YAML/JSON in settings.yaml or a custom settings file, or an array/scalar at its root | Back up the settings file named in the error, then rename only that file and start dsh web; re-save needed models, providers, and UI settings afterwards. Do not alter .credentials.yaml. |
failed to parse overlay, must be a top-level YAML array, or overlay entry ... must be a mapping | A cordis.patch.yml shape is not a valid Loader patch | Use the dump commands below to determine whether the patch is profile-level or home-level. Back up and temporarily rename only the named patch file, then retry. |
failed to apply loader entry ... | A plugin's configuration, dependency, or startup failed | Follow the final nested cause in the full stack to the specific plugin. Verify the default composition first, then inspect that profile's dependencies and patch. |
profile "<name>" does not exist | A non-built-in profile was never created; only web and headless initialize automatically on first use | Create the requested profile with dsh plugin --profile <name> add <package> as the error suggests; do not copy an entire unrelated profile directory by hand. |
Cannot find package ... or ERR_MODULE_NOT_FOUND | Profile plugin dependencies are incomplete, an upgrade left incompatible dependencies, or a source checkout has not been built | Installed CLI: run dsh plugin --profile <name> install and retry. Source checkout: run pnpm run build at the repository root, then launch with pnpm dsh .... |
Use config dumps to separate default composition from custom patches
For cordis.patch.yml, failed to apply loader entry, or module-resolution errors, run these through the same DSH installation:
dsh --profile web --dump-default-config
dsh --profile web --dump-configThe first command checks only the bundled composition. The second also reads the profile cordis.patch.yml, ~/.dsh/cordis.patch.yml, and any command-line overlay.
- Only the second command fails: investigate the named user patch first; back up and move aside that single file, then restore changes one at a time.
- Both commands fail: the current DSH installation, in-box bundles, or that profile's dependencies are more likely involved. Confirm the running version and the result of
dsh plugin --profile web installfirst. - Both commands pass but
dsh webfails: read the innermostcause; it normally names a plugin configuration, port, or credentials file. Then use the matching entry on this page.
One rule for pre-release versions
DSH remains in developer preview. Let one CLI version manage one $DSH_HOME at a time, and back up before updating. After an upgrade, downgrade, or Node / nvm switch, use the actual loaded path in the traceback to verify the version before choosing to migrate, restore an old file, or re-enter credentials.
Model and network
| Symptom | Cause | Fix |
|---|---|---|
| Model does not respond or times out | Invalid key, no network access to the endpoint, or a wrong Base URL | Check key validity, endpoint reachability and Base URL; see configure models |
| Requests are blocked or time out through a proxy | Misconfigured proxy environment variables | Check HTTP_PROXY / HTTPS_PROXY and make sure the proxy does not block the model endpoint |
MISSING_CREDENTIAL | A provider credential is missing | Store the key via the models page, or provide the referenced environment variable |
UNKNOWN_MODEL | The requested model is not configured | Select a configured model, or add the missing model to your custom provider |
| "Fetch available models" returns 401 | Wrong key, or the service has no GET /models | Check the key; for services without that endpoint, enter models manually |
| New sessions still use the old model | Sessions that already sent requests keep the model recorded in their log | Switch in the model selector; the choice only becomes the default for new sessions |
| The input shows "Select model" and blocks input | The saved default points at a deleted provider | Select a model again |
| Image rejected before sending | The model does not declare image modality | Add input: [text, image] to the custom provider's model; DeepSeek's own chat-completions route is text-only and cannot be changed by config |
| The provider rejects a request with an image | The model declares an image capability its endpoint does not support | Remove image from the list granting it (the model's input or the route's defaultInput), then start a new session |
Port conflicts
| Symptom | Cause | Fix |
|---|---|---|
Startup fails immediately with EADDRINUSE | The default port 3080 is already taken | Pick another port: dsh --profile web --port 8080 (--port belongs to the web app); or free the occupying process first |
| The actual listening port is unclear | With port 0, the OS assigns the port | Use the address the command prints |
Workspace
| Symptom | Cause | Fix |
|---|---|---|
| Session input is disabled | No workspace is selected | Click Select Workspace, add and select the directory where you launched dsh |
| File read/write is denied | The operation is outside the sandbox-authorized workspace | Move the target files into the workspace, or adjust the permission preset; avoid over-broad access |
| Expected files are not found | The workspace points at the wrong directory | Re-select the correct project directory as the workspace |
Permissions and approvals
| Symptom | Cause | Fix |
|---|---|---|
| Operations keep asking for approval | The current permission preset asks on each sensitive action | Review the permission preset; keep a level that asks (such as workspace-write) for daily use |
| Operation denied by the sandbox and cannot escalate | A subject must not gain permissions beyond its existing grants (non-escalation) | Retry within what the permission preset allows; when genuinely wider access is needed, switch the preset or explicitly approve that call yourself |
Restricted sandbox reports SANDBOX_UNAVAILABLE | The environment has no backend for the requested sandbox | Switch to a sandbox mode or preset available in this environment |
Build errors
| Symptom | Cause | Fix |
|---|---|---|
pnpm run build fails | Wrong Node version, incomplete install, or an unsynced checkout | Confirm Node ^22.19 or >=24, re-run pnpm install, then retry pnpm run build |
| Source launch reports a module-resolution error | The build was not run first | Run pnpm run build before pnpm dsh <args...>; see installation |
Still stuck?
If none of the above matches, bring your reproduction steps, Node version and error messages to the community.