dsh startup failure: a four-layer decision tree
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?
- Run
which -a dshand see whether multiple paths appear; - Run
dsh --versionand note whether it prints or errors; - Run
type dshand confirm no alias or shell function hijacks it; - 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?
node -vand compare against the version range in the documentation;npm -vandnpx -v, confirming both come from a normal install;- Run
npm pingor reach the registry once, checking network and certificates; echo $DSH_HOMEand confirm the directory is writable;- 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?
- Run
lsof -i :3080and look for an existing owner; - Read the listen address in the startup log, normally
127.0.0.1:3080; - Run
curl -Iagainst the bound address and confirm a response rather than a refusal; - If
--hostwas set, confirm the bound address is the one clients use; - 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?
- Read the last thirty lines of the startup log and find the first error, not the last;
- Record the installed plugin list for the active profile;
- Disable or remove the most recently added plugin and restart;
- If it still fails, restore half and repeat to narrow down;
- 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.
| Layer | The one question | Key command | Passes when |
|---|---|---|---|
| Command | Which dsh is executed | which -a dsh | One path, version prints |
| Environment | Are runtime and network enough | node -v, npm ping | Supported version, registry reachable |
| Port | Is the service listening | lsof -i :3080 | One listener, responds |
| Plugin | Did the profile assemble | Plugin list plus log | Minimal 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.
- Treating "command not found" as not installed, when PATH was simply not reloaded;
- Treating "download failed" as a network outage, when a certificate expired;
- Treating a blank page as a port problem, when front-end assets never loaded;
- Treating a plugin error as a broken core, when the profile was wrong;
- 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:
- The command layer confirms an install but the executable is corrupt, and a clean reinstall reproducibly fixes it;
- The environment passes yet initialization crashes with no readable log entry;
- The minimal plugin set still fails and the profile directory cannot be repaired;
- 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
FAQ
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.
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.
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.
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
- DeepSeek Harness docs· deepseek-harness
- dsh CLI README· deepseek-ai
- deepseek-harness repository· deepseek-ai