Help & Ecosystem
Troubleshooting
Diagnose install dependencies, 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.
Run these in order first; they rule out most cases:
- Node version:
node --version should meet ^22.19 or >=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.
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
If none of the above matches, bring your reproduction steps, Node version and error messages to the community.
