Fix 'cannot read properties of undefined': DSH plugin

If every tool call starts failing with TypeError: Cannot read properties of undefined (reading 'prepare') after you install a third-party DSH plugin, and the UI shows a failed run, do not rush to reinstall the whole environment. The error does not mean "a plugin feature broke"; it means the tool dispatch layer received a registry object that was never assembled correctly: code reads its prepare method and gets undefined. The trigger is usually in assembly — some plugin resolved a second copy of the core tool package (Source: Discussion #1486). This guide covers three things: what the error precisely means and its typical symptoms, a three-step triage that narrows the cause to a specific plugin, and how to handle the three common root causes. To understand plugin-to-plugin dependency relationships, see how to fix a duplicate core package.

What the DSH plugin error reading 'prepare' means: read it precisely first

This error is a JavaScript runtime error saying code read a property from an undefined value; appearing early in tool dispatch places the problem in the dispatch layer rather than in a specific tool (source). Unpack the raw error:

TypeError: Cannot read properties of undefined (reading 'prepare')
    at ToolDispatcher.dispatch (.../tool-dispatch.js:...)
    at async SessionRunner.runTurn (.../session-runner.js:...)

Three pieces of information decide the triage direction:

The symptoms in the community report match exactly: after installing a third-party plugin that depends on @deepseek-ai/dsh-tools, any conversation fails in the tool-call stage and the UI shows a failed run, while the headless profile works fine (Source: Discussion #1486). "Every call fails" plus "a different profile fixes it" are the key features that separate this from "one tool is unusable" or "the model cannot connect".

Locate this error in DeepSeek Harness: a three-step triage

The triage order is confirm scope first, then inspect dependencies, then bisect plugins — each step producing a falsifiable conclusion, so you avoid simply reinstalling. Concretely:

1. Confirm the failure scope. Open a new session and have it call one basic file-reading tool; then switch to the headless profile and run the same prompt. Record two facts: whether every call fails, and whether headless works. If headless works, the suspect narrows to the extra plugins the web profile loads (Source: Discussion #1486).
   • Expected: a definite conclusion of "global failure, web only" or "localized failure", rather than just "it errors".
2. Check how many copies of the core tool package the dependency tree holds. Run a dependency-tree query in your plugin directory and see how many times @deepseek-ai/dsh-tools appears and whether the versions match.
   bash

   npm ls @deepseek-ai/dsh-tools --all
   

   • Expected: if the output shows two different resolution paths (say one from the framework itself and one from a plugin's node_modules), you have basically hit the root cause — duplicate resolution (Source: Discussion #1337).
3. Bisect down to a single plugin. Disable half of the recently added third-party plugins in your configuration, restart dsh web, and retest; if the error disappears, bisect that half, otherwise check the other half.
   bash

   dsh plugin --profile web list
   dsh plugin --profile web remove <suspicious-plugin>
   

   • Expected: eventually a single plugin name is pinned down that reproduces reliably — install it and the error appears, remove it and it is gone.

After these three steps you hold a reproducible conclusion, for example "after installing plugin X, every tool call under the web profile reports the prepare error, and removing it restores everything". Fixing with that conclusion avoids spinning in reinstall loops.

Three common root causes and how to fix each DSH plugin case

Almost all errors of this kind fall into three classes: duplicate core-package resolution, a plugin-to-core version mismatch, and missing plugin initialization; each class needs a different action. Work through the table:

The first class is by far the most common. Its mechanism: the plugin installs another copy of @deepseek-ai/dsh-tools in its own dependencies, so the plugin registers into copy A's registry while the dispatch layer reads copy B — the two are not the same object, and prepare is naturally not found (Source: Discussion #1337). The principle is "keep exactly one copy of the core package", rather than suppressing the error. The second and third classes map to version and initialization respectively, and upgrading the plugin or completing configuration usually resolves them.

Notes when fixing this DSH plugin error

1. Collect evidence before acting. Until you know which plugin, under which profile, and whether it reproduces reliably, reinstalling only puts the same conflict back.
2. Use headless as a control. If the same prompt works under headless, the core chain is fine, and the problem is in the web-side plugin assembly.
3. Do not mask the error with deletion or try/catch. A missing object in the dispatch layer is an assembly problem, and suppressing the error only makes later behaviour more unpredictable.
4. Rolling back beats forcing a fix. If a plugin conflicts with the current core version and no matching version exists, uninstall it and switch to an overlapping alternative; for options, see DSH Plugin Hub.
5. Run a regression after fixing. At minimum run one full multi-step tool sequence (read a file → edit a file → run a command) to confirm the dispatch layer also works across consecutive calls.

Sources: Discussion #1486, Discussion #1337, tools subsystem (DeepSeek Harness docs).