ChatGPTClaudeGrok / X / CursorGemini

dsh startup failure: a four-layer decision tree

TroubleshootingPublished 2026-11-02Author: DeepSeek Plugin Market
dsh startuptroubleshootingdecision treeDeepSeek Harnessport
When the only symptom is "it will not start", check command, environment, port, and plugin in that order. Each layer has one question, a check, and an exit.

Do not begin a startup failure with a reinstall. Work from the outside in: command, environment, port, plugin. The four layers depend on each other, so conclusions drawn at inner layers while an outer one is broken are fiction.

dsh layer 1: the command and why the order is fixed

"It will not start" is a result, not a cause; any of four layers produces the same sentence. Without an order, people change Node, change the port, and delete plugins simultaneously — and if it then starts, nobody knows which change did it, so it returns next week.

Each layer answers one yes/no question. Here is what to ask, what to run, and where each answer sends you.

With the order settled, the first layer is the command itself.

This layer answers one thing: which file does the terminal actually execute?

  1. Run which -a dsh and see whether multiple paths appear;
  2. Run dsh --version and note whether it prints or errors;
  3. Run type dsh and confirm no alias or shell function hijacks it;
  4. If you use npx, verify separately with npx @deepseek-ai/dsh --version.

Passing means: one path, a printed version, no redirecting alias.

Exits: no output from which means nothing is installed or PATH omits the install directory; output plus a permission error means the file is not executable; type naming an alias means a shell profile was edited. All three belong here, and all three are retested here.

dsh layer 2: the environment

This layer answers: the command exists, but are its runtime and network conditions satisfied?

  1. node -v and compare against the version range in the documentation;
  2. npm -v and npx -v, confirming both come from a normal install;
  3. Run npm ping or reach the registry once, checking network and certificates;
  4. echo $DSH_HOME and confirm the directory is writable;
  5. If a proxy is in use, confirm the proxy variables match the actual egress.

Passing means: a supported Node version, a reachable registry, a writable data directory.

Exits: upgrade Node when it is too old; fix proxy or mirror when the registry is unreachable; fix permissions or move DSH_HOME when it is read-only. Environment failures usually carry download or write errors, so those keywords send you here directly.

dsh layer 3: the port

This layer answers: is the service actually listening where you expect?

  1. Run lsof -i :3080 and look for an existing owner;
  2. Read the listen address in the startup log, normally 127.0.0.1:3080;
  3. Run curl -I against the bound address and confirm a response rather than a refusal;
  4. If --host was set, confirm the bound address is the one clients use;
  5. Check host firewalls or security software for local port blocking.

Passing means: exactly one listener, a response to curl, and a bound address that matches what you open.

Exits: a busy port means change ports or stop the other process; curl works but the browser does not, so rule out browser proxies first; bound to loopback while requesting another machine's address is an addressing problem. Change one thing and retest.

dsh layer 4: the plugin

This layer answers: the service starts, but did the profile assemble successfully?

  1. Read the last thirty lines of the startup log and find the first error, not the last;
  2. Record the installed plugin list for the active profile;
  3. Disable or remove the most recently added plugin and restart;
  4. If it still fails, restore half and repeat to narrow down;
  5. Check the profile directory for half-installed leftovers.

Passing means: the minimal plugin set starts cleanly.

Exits: once a package is identified, check whether its version matches the running dsh version, and whether it went into the profile that actually starts. Wrong profile and version mismatch account for most plugin failures.

With all four layers walked, put them side by side once so the order sticks.

Seeing them side by side shows which step comes first.

LayerThe one questionKey commandPasses when
CommandWhich dsh is executedwhich -a dshOne path, version prints
EnvironmentAre runtime and network enoughnode -v, npm pingSupported version, registry reachable
PortIs the service listeninglsof -i :3080One listener, responds
PluginDid the profile assemblePlugin list plus logMinimal set starts

The order cannot be shuffled because an outer failure invalidates every inner observation. If PATH points at an old version, no amount of plugin work helps.

dsh misjudgments and when a reinstall helps

A misjudgment costs more than a missing check, because it drives repeated wrong actions — so ask which layer a symptom belongs to before touching anything.

  1. Treating "command not found" as not installed, when PATH was simply not reloaded;
  2. Treating "download failed" as a network outage, when a certificate expired;
  3. Treating a blank page as a port problem, when front-end assets never loaded;
  4. Treating a plugin error as a broken core, when the profile was wrong;
  5. Treating "fails after restart" as flaky, when the old process never exited.

Only after ruling out misjudgments does a reinstall become the fallback.

Reinstalling is the last resort, not the first reaction. Consider it only when:

  1. The command layer confirms an install but the executable is corrupt, and a clean reinstall reproducibly fixes it;
  2. The environment passes yet initialization crashes with no readable log entry;
  3. The minimal plugin set still fails and the profile directory cannot be repaired;
  4. DSH_HOME was migrated and the data directory structure is suspect.

Back up DSH_HOME first. Settings, sessions, and credentials live there; deleting and reinstalling starts you at zero.

dsh next steps

Walk the four layers before changing configuration. For reading a single command error, read dsh startup command errors. For common causes of a failed start, read dsh startup failed. For port conflicts in detail, read fixing dsh port conflicts. For configuring the listen address and port deliberately, read dsh startup flags.

Sources: DeepSeek Harness docs, dsh CLI README, deepseek-harness repository

ChatGPTClaudeGrok / X / CursorGemini

FAQ

Why check the command layer before reinstalling when dsh will not start?

The dsh command layer is the only layer that explains whether the command ran at all, and it costs two commands to check. Reinstalling overwrites evidence, while which -a dsh and dsh --version decide the question immediately.

The port answers and the page opens. Should I still check the plugin layer?

A dsh page that opens but is blank or missing features is no longer a port problem, so the plugin layer is still worth checking. A passing port check only means the service is listening, not that the profile assembled correctly.

All four layers checked and it still fails. What should I keep before asking for help?

The last thirty lines of the startup log, dsh --version, the DSH_HOME path with a shallow directory listing, and the listener state for the port. Together these cover most judgments better than a full-screen screenshot.

Disabling every plugin makes it start. Does that name the culprit?

It names the layer, not the plugin. Restore half the plugins, test, and repeat; a few rounds narrow it to one package, whose version and profile you then check.

Related Terms

decision tree
A decision tree is a fixed sequence of questions where each layer answers one thing and determines the next step, so no two components are suspected at once.— DeepSeek Harness docs
command layer
The command layer is the first check, confirming that the `dsh` the shell finds is the executable you think it is.— dsh CLI README
profile
A profile is a named assembly environment with its own dependencies and patches; a plugin installed into another profile does not load.— dsh CLI README
DSH_HOME
DSH_HOME is the data root for DeepSeek Harness, defaulting to ~/.dsh, holding settings, sessions, plugins, and credentials.— DeepSeek Harness docs

Sources