dsh startup errors: command not found, settings unavailable

Startup errors look varied but sit in three layers: the command is missing, pnpm is missing, or a plugin fails to initialize. Identify the layer; mixing them leads to reinstalling in the wrong place.

Three layers first

Classify by where the error appears, not by its wording.

Command layer comes first. If dsh is not found, plugin errors are meaningless; npx separates "not installed" from "wrong path."

Package management comes second. The command runs but plugin operations report pnpm; that is an environment issue, not a plugin issue.

Plugin loading comes last. Only after the first two pass do you inspect modules and fields.

Layer one: command not found

Four wordings, one cause: the system cannot find the executable.

1. zsh: command not found: dsh. macOS and Linux; check global install and npm global bin on PATH.
2. dsh not found. Same class; shell configuration may need a reload.
3. 'dsh' is not recognized as an internal or external command. Windows CMD or PowerShell; check install location and PATH.
4. dsh command does not exist. Same meaning; confirm the install method.

The fastest test is npx. Run npx @deepseek-ai/dsh --version. A version means the package exists and PATH is wrong; the same error means installation failed (source).

Do not guess at PATH. Check whether the global bin directory is listed, then reopen the terminal; fixing only the current session disappears on restart.

Layer two: pnpm and dependencies

The command runs, but profile plugin operations report pnpm.

1. Check whether pnpm is installed: pnpm -v.
2. If missing, install it and configure PATH persistently; temporary exports vanish.
3. Re-run the failing command and confirm the pnpm error is gone.
4. If pnpm exists but fails, check for version conflicts with which pnpm.
5. Start again and confirm the plugin chain works.

pnpm is required for the plugin chain. Substituting npm may appear to install but fail at load, which is harder to diagnose.

Multiple versions are subtler than absence. A version mismatch may produce errors pointing at another module; confirm the binary actually used.

Layer three: plugin loading

With the first two layers healthy, startup failures point at plugins.

1. cannot read properties of undefined (reading 'prepare'). Initialization read an empty object; often version, build output, or dependency related.
2. crypto.randomUUID is not a function. The runtime lacks the API; common on older runtimes or across web environments.
3. settings are unavailable in this browser. The browser cannot read settings; entry, cache, or permission related.
4. failed to load plugins. The whole load phase failed; read the first failing plugin in logs.

The order is locate plugin, check version, disable and compare. Disabling all plugins proves "a plugin is at fault" but not which one; disable one at a time.

Diagnostic order: outside in

Command, package management, plugin; this order avoids duplicate work.

1. Compare with npx to check the command layer.
2. Check pnpm and PATH for the package layer.
3. Read the first failing plugin in logs.
4. Disable the suspect and retest startup; recovery identifies it.
5. Upgrade or roll back that plugin and retest.

Change one thing per step. Changing PATH, pnpm, and plugins together hides which one fixed it.

Record each result. Command works, pnpm available, which plugin disabled; the next incident can compare.

Verify after fixing

Starting is not proof; verify three signals.

1. Command signal: dsh --version prints a version.
2. Load signal: startup logs show no failures and the plugin list is readable.
3. Function signal: open a session, run one minimal operation, and confirm the plugin entry works.

All three must pass. A startup screen alone may mean a failed plugin was skipped while the app continued.

Keep the logs. Comparing before and after shows whether anything actually changed.

Prevention: upgrade and install boundaries

Most startup errors come from changing several things at once.

1. Separate core and plugin upgrades: core first, then plugins.
2. Upgrade one plugin at a time: failures are immediately attributable.
3. Keep a rollback version: record pre-upgrade versions and configuration.

Boundaries are about diagnostic cost. One variable per change keeps one clue per problem.

Next steps

Classify, then fix layer by layer. For command lookup, read dsh command not found. For prepare errors, read cannot read properties of undefined reading prepare. For load failures, read Plugin load and activation failures.

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