Troubleshooting

Use --port when 3080 is taken, allow git-hosted plugins in pnpm-workspace.yaml when allowBuilds blocks them, and check the API key in Settings → Models when a model fails. Inspect dsh --dump-config first, then fix the symptom.

This category offers reproducible fixes for common DeepSeek Harness Plugin (DSH plugin) issues: use --port when 3080 is taken, allow git-hosted plugins in pnpm-workspace.yaml when allowBuilds blocks them, check the API key in Settings → Models when a model fails, and fall back to dsh --profile headless for one-shot tasks when the Web UI won't open. Every fix cites official sources and tracks DeepSeek Harness releases.

DSH Plugin tutorial list

All93Concepts & Architecture28Install & Get Started46Configuration & Usage33Update & Upgrade33Uninstall & Cleanup29Troubleshooting93Plugin Development30
Troubleshooting2026-09-24

dsh plugin market not loading? Proxy, registry and 403 fixes

DeepSeek HarnessDSH pluginplugin marketnot loadingtroubleshooting

dsh plugin market not loading? Three cases: no Hub entry, an empty list, or an error. Check timeout, 404 and 401/403 separately, each with its own fix.

Troubleshooting2026-09-12

DeepSeek Harness slow startup: causes and fixes for dsh

DeepSeek HarnessDSH pluginslow startuptroubleshootingperformance

Slow dsh startup has three causes: first-run profile init, per-start bundle composition, or a hang on a timeout. Measure with time and --dump-config.

Troubleshooting2026-09-12

Fix custom agent presets not loading in DeepSeek Harness

DeepSeek HarnessDSH pluginagent presetroots overwrittencomposeProfile

A custom agent preset never shows in the DeepSeek Harness picker: a boot-time override replaces agent-presets.roots with the shipped root.

Troubleshooting2026-09-12

DSH plugin startup: HTML did not preload client.js

DeepSeek HarnessDSH pluginclient-modulesmodule preloadbuild artifacts

DeepSeek Harness shows Failed to load plugins; the console reports client-modules: HTML did not preload client.js. Same-page-load evidence and the checklist.

Troubleshooting2026-09-12

DSH plugin blank session: duplicate tool call ids break load

DeepSeek HarnessDSH pluginblank sessionduplicate callIdreceived more than one start Match

A DeepSeek Harness session that refuses to open or opens blank usually shares one cause: a callId advertised twice in one step breaks the assembler.

Troubleshooting2026-09-12

Fix EISDIR on exFAT drives in DeepSeek Harness write tool

DeepSeek HarnessDSH pluginEISDIRexFATEPERM mkdir

The DeepSeek Harness write tool fails every time on exFAT volumes with EISDIR even for a new file: the volume has no hard links and libuv mis-maps the failure.

Troubleshooting2026-09-12

Fix ask_user_question in DeepSeek Harness goal rounds

DeepSeek HarnessDSH plugingoal roundask_user_questionagent spin

In an autonomous DeepSeek Harness goal round the model calls ask_user_question, you answer, and nobody receives it, so the agent spins for dozens of rounds.

Troubleshooting2026-09-12

DSH plugin HMR: "--expose-internals is required"

DeepSeek HarnessDSH pluginexpose-internalsHMR servicesource mode

Running pnpm dsh web from source exits with --expose-internals is required for HMR service: web disables HMR, then boot mounts a watch-only instance anyway.

Troubleshooting2026-09-12

DSH plugin hook matcher: Bash does not match bash

DeepSeek HarnessDSH pluginhook matchercase sensitivityClaude compatibility

Copied a hooks.json from Claude Code with matcher "Bash" and the hook never fires? The literal matcher is case-sensitive and silently skips the miss.

Troubleshooting2026-09-12

Fix Body Timeout Error with local models in DeepSeek Harness

DeepSeek HarnessDSH pluginBody Timeout Errorlocal LLMstreamIdleTimeoutMs

DeepSeek Harness local models fail at 5 min with Body Timeout Error? Two 300s gates — undici bodyTimeout and the idle watchdog — must be raised together.

DSH troubleshooting FAQ

DSH says port 3080 is in use. What do I do?

The Web UI listens on 3080 by default; start it elsewhere with dsh --profile web --port 8080. --port is a web-app argument that goes after the profile.

My DSH plugin installed but does not load. Why?

First confirm compatibility with your DSH version. Git-hosted plugins can be blocked by pnpm's allowBuilds security policy — add the allow key to the profile's pnpm-workspace.yaml and reinstall.

My model keeps failing to connect. How do I debug it?

In Settings → Models, confirm the API key is saved and the right model is selected; routes apply immediately. Custom endpoints use OpenAI-compatible config — verify base URL and model name per the official docs.

The Web UI opens blank. What should I do?

Check the browser console and terminal logs to locate the stage, then verify the config. If the UI cannot recover, run dsh --profile headless "task" to execute via CLI and keep working.

How do I quickly confirm my DSH config is correct?

Run dsh --dump-config to view the merged config tree and compare it with dsh --dump-default-config defaults. Both are read-only.