DSH plugin incompatible? Rollback DeepSeek Harness update

When a DSH plugin becomes incompatible after an update, confirm the symptoms first, then act: pin the plugin back to an old version or downgrade the DSH core — and check compatibility before upgrading next time.

Overview

Post-update plugin incompatibility often fails silently instead of throwing errors. The fix has three steps: recognize the symptoms, roll back the plugin or downgrade the core, and check compatibility before future upgrades. DSH is in developer preview (currently 0.1.0-rc.6), so breaking changes can land at any time (source). Plugin authors follow the core at different speeds, so "the core upgraded but the plugin did not" is the most common trap in preview builds. This article walks through symptoms, rollback, and prevention — back up before touching anything, and don't reinstall over and over before you know the cause.

Typical symptoms of an incompatible DSH plugin

An incompatible plugin usually means a missing capability, not a red error. Three common signs:

1. A UI plugin changes nothing and a tool plugin is absent from the tool list — installed but invisible.
2. The plugin logs errors when it loads at startup.
3. A plugin that worked stops immediately after the DSH core updates.

For symptom 2, read the terminal that runs dsh web when a plugin fails at startup — a plugin that throws during apply(ctx) prints a stack trace there, and the first line usually names the plugin. Comparing that name with what dsh --dump-config shows tells you "failed to load" apart from "never installed", which changes what you fix.

To confirm whether a plugin actually loaded, run dsh --dump-config and check the merged config tree — a registered plugin shows up there at a glance (source). For example: a tool plugin that used to appear in the terminal's tool list stops showing up, or a UI plugin's custom theme no longer applies after the core upgrade. Because nothing prints a red error, many users reinstall the plugin repeatedly — which changes nothing, because the version is the problem, not the installation. Run dsh --dump-config before touching anything to confirm whether the plugin is even registered.

Two more facts worth collecting before acting: dsh plugin --profile web why <package> shows who depends on the plugin, and pnpm list in the profile directory shows which version is actually installed. Together they tell you whether the plugin loaded, which version is running, and who depends on it — three facts that decide whether you roll back the plugin, downgrade the core, or do nothing at all. One judgment point before acting: only the "broke right after a core update" case is worth a plugin rollback. If the plugin broke right after it updated, suspect the package itself and follow the update-failure article instead.

How to roll back a DSH plugin or downgrade the core

There are two paths: pin the plugin back, or downgrade the DSH core. Pick by situation:

• Plugin rollback: dsh plugin forwards arguments to pnpm, so adding a version after the package name pins it back:
  bash

  dsh plugin --profile web add <package-name>@<old-version>
  

  Restart dsh web and the plugin reverts to the old version's behavior. Not sure which old version to use? Run pnpm list in the profile directory to see what is installed, or check the version history on the plugin detail page — don't guess a version number that does not exist. After the rollback command, don't assume the old version is active: run pnpm list again to confirm the version, then restart dsh web and exercise the feature that broke. In preview builds a plugin's "old version" may itself have been broken — if the feature still fails after a clean rollback, the problem may be in the plugin's own release history, not the core.
• Core downgrade: with npx, run a pinned version npx @deepseek-ai/[email protected] web; with a source build, find the commit with git log --oneline, git checkout <commit>, then pnpm install && pnpm run build.

Back up the session data under ~/.dsh/sessions before rolling back; for more details see Fix DeepSeek Harness Update Failure. After rolling back, don't just move on: load the broken plugins one by one to confirm the features are back, then decide whether other plugins should also be pinned to compatible versions. In a preview release, change one thing at a time so issues stay easy to locate.

How to avoid DSH plugin incompatibility after updates

Checking compatibility before upgrading is the cheapest way to avoid breaking things. Concretely:

1. Check the compatible DSH version on the plugin detail page before upgrading — a mismatch can fail silently.
2. With DSH Plugin Hub installed, verify in Settings → Plugin Center: it lists 4,401 human-curated plugins synced daily, and each card declares the compatible version and verification status — review before updating the core.
3. Verify core features one by one after a bulk update, and pin back any incompatible plugin with the rollback command above.
4. Before a core major update, confirm your installed plugins declare a matching compatibility target (the detail page shows it).

A practical habit that turns this into routine: before upgrading the core, snapshot the current state — note which plugins you rely on and their versions (the detail page or pnpm list). Then upgrade the core, run dsh --dump-config to confirm every plugin still registers, and exercise the features you use daily. If something is missing, you now have a concrete list of "what to pin back" instead of guessing.

One last piece of advice: in a preview release, don't chase "always latest". If your core workflow runs fine, hold off on core upgrades. When you do upgrade, do it early on a workday so you have the afternoon for verification and rollback. Making "check compatibility before, verify features after" a habit beats any fix command.

Source: dsh CLI README, official Quickstart, dshplugin/dsh-plugin-hub