Take a diagnostic snapshot before changing state

Record the DSH package version, Node or Python version, OS/environment, exact command, time, workspace location, provider type, and the smallest relevant error excerpt. Remove API keys, authorization headers, file contents, personal paths, and unrelated environment variables before sharing.

Safe diagnostic outline · text
DSH version:
Runtime version:
OS / native or WSL:
Command or UI action:
Expected state:
Actual state:
Last boundary that worked:
Redacted error excerpt:

Process does not stay running

First distinguish package resolution, runtime incompatibility, port conflict, configuration parse failure, and process crash. A browser error is secondary if the process never reports a listening address.

  • Can npm resolve and execute the package?
  • Does the process print an actionable error before exit?
  • Is the configured port already in use?
  • Does a clean profile start?
  • Did the failure begin after a DSH or plugin update?

Process runs but the Web UI does not open

Use the exact address printed by DSH. Confirm host, port, local firewall, container/WSL boundary, and trusted-host configuration. Do not expose a development server to a public interface merely to bypass a local routing problem.

UI opens but the model cannot run

Separate credential resolution, model identity, endpoint authentication, model capability, and upstream service errors. Test a minimal text-only request before tools, images, or long context.

  • Missing credential → resolve the expected secret reference.
  • Unknown model → verify provider and exact model ID.
  • 401 → verify key-to-endpoint ownership.
  • Input capability error → verify model modality.

Core task works but a plugin or MCP server fails

Disable the extension and confirm the base task still works. For plugins, inspect install, load, and feature stages separately. For MCP, inspect transport startup, namespace, environment/header reference, timeout, reconnect, and whether the requested capability is a Tool rather than an unsupported Resource or Prompt.

Failures already reproduced

HarnessBase reproduced one plugin loader mismatch and one MCP outage boundary. On DSH rc.7, dsh-deepseek-vision 0.1.4 failed with the exact keyed-slot options.key diagnostic; upgrading to 0.1.5 restored the normal UI across two starts. dsh-oomol 0.1.4 produced the same settings-slot signature twice, but no fixed package version was available. For Streamable HTTP MCP, stopping the endpoint produced the exact error “fetch failed”; restarting the same endpoint let the existing DSH process call the tool again in 28 ms.

Why this hub is still noindex

One plugin repair and one MCP outage/recovery path are now retained, but a reliable troubleshooting hub needs a much broader issue corpus and reproduced fixes. Startup, provider, workspace, WSL2, Linux, macOS, TLS, proxy, and production-auth branches remain incomplete rather than being padded with speculative fixes.

Sources and evidence boundary

Primary sources establish product facts. HarnessBase labels direct testing separately and does not convert community observations into verified results.

Target query cluster: DeepSeek Harness not working · DeepSeek Harness error · DSH troubleshooting