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

All9Concepts & Architecture1Install & Get Started3Configuration & Usage1Update & Upgrade1Uninstall & Cleanup1Troubleshooting1Plugin Development1
Troubleshooting2026-08-19

DSH troubleshooting: port in use and plugins not loading

DSHDeepSeek HarnessDSH plugintroubleshootingFAQ

Common DSH issues: port 3080 in use, plugins not loading, models not connecting, and a blank Web UI — with fixes for each.

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.