Look up by error, not by chapter
Error text → possible cause → fix direction → how to verify.
Plugin rejected by the version gate: stays in the list but does not run
Possible cause: The engines.dsh host range declared by the plugin doesn't match the current version; community plugins commonly open up only for a specific 0.2.x generation.
Fix direction: Check the plugin repository's CHANGELOG and README to find the host versions it supports; either switch to a supported host version or install an older build of the plugin targeting the older host. Do not install @latest.
How to verify: After a restart, check that the plugin status is Enabled, then run a minimal task to confirm the tool works.
Compiled from public sources Source: Community plugin CHANGELOG
Opening the bare address 127.0.0.1:3080 shows 'authentication required'
Possible cause: The web start command prints a full access URL with a one-time token in the terminal; hitting the bare address without the token gets rejected.
Fix direction: Go back to the terminal that started dsh web and copy the full URL it printed; if you restarted the service, grab a fresh one because the old token is invalidated.
How to verify: The full URL opens the session page with no need to enter the token again.
Compiled from public sources Source: Local hands-on experience / official documentation wording
Opening the settings page returns HTTP 403
Possible cause: Community reports mostly point to browser extensions blocking local requests, such as Page Assist.
Fix direction: Disable such extensions first and refresh; if it still fails, check the Host log to confirm whether the request arrived.
How to verify: The settings page opens and a config change can be saved.
Not yet reproduced Source: Community tutorial
UNKNOWN_TOOL / HTTP 400 when using a third-party OpenAI-compatible gateway
Possible cause: The English-language community attributes these errors to gateway compatibility differences around the developer role, tool names, and tool-call format.
Fix direction: First check whether the gateway supports the tool-call format of the model in use, then verify the Base URL and model ID; keep the raw error and request body for comparison.
How to verify: Test with a single minimal tool call and see whether the same error still appears.
Not yet reproduced Source: findharness troubleshooting article (English)
Plugin installs successfully but fails to enable, or disappears after a restart
Possible cause: Starting with 0.2.2-alpha.3, the upstream project separated the diagnostics for 'installation failed' and 'enable-after-install failed'; there are also community reports of upgrades overwriting config.
Fix direction: Check the Host log to tell which step failed; if an upgrade is involved, restore the config from the pre-upgrade backup first, then reinstall that plugin on its own.
How to verify: After a restart the plugin is still in the installed list and its status is Enabled.
Not yet reproduced Source: Community ecosystem report
dsh-cost-meter cost-detail popup reports Ne.async is not a function
Possible cause: Community hands-on feedback: a newer plugin build doesn't match the current core; clicking the 'cost detail' popup on a session throws and the UI doesn't render, while the bottom-bar live stats and settings page work.
Fix direction: Rely on the bottom-bar / settings-page cost stats for now; watch for a plugin update or reinstall on a supported host version; don't conclude the plugin is fully broken.
How to verify: After updating the plugin or moving to a supported host version, does the cost-detail popup open normally.
To reproduce Source: Community hands-on article
Plugin market Discover page times out / index source 15s timeout
Possible cause: Community feedback: dsh-market's Discover page gives the index source only 15 seconds, and the GitHub Pages index can exceed that on some networks, so plugins can't be searched.
Fix direction: Use a faster index source: in Discover, set the index source to jsDelivr's https://cdn.jsdelivr.net/npm/dsh-plugin-catalog/index.json, or dshmarket.com's index; or search directly inside dsh-market.
How to verify: Open Plugins -> Discover and confirm you can search and install plugins.
To reproduce Source: Community plugin-market notes
Plugin config entries drop sharply after upgrade (e.g. 34 to 2) and first launch fails
Possible cause: Community incident report: a Windows user upgrading from 0.2.1-rc.5 saw plugin entries shrink from 34 to 2 and the first launch fail due to an incompatible localization plugin; the client had no pre-upgrade auto-backup or rollback then.
Fix direction: Restore from a pre-upgrade profile config backup (manual recovery took hours). Always back up $DSH_HOME config and profile directories before upgrading.
How to verify: After restore, plugin entry count recovers and the app launches normally.
To reproduce Source: Community incident report (not reproduced here)
billion-context seems to lose content after compaction / savings numbers look wrong
Possible cause: The compaction plugin folds early turns into summaries; if the incremental-parse grey release or cache toggle isn't matched to your setup, recall may degrade or savings become unreliable.
Fix direction: Open the plugin's 'bili settings' and align the cache / incremental-parse toggles with your upstream (whether it caches via prompt_cache_key); if you suspect loss, turn off incremental-parse grey release and compare.
How to verify: Probe the same early facts before and after compaction; do the numbers make sense (savings and net savings same sign and comparable magnitude).
To reproduce Source: Community plugin notes
dsh-vision-router gives no response / returns 429 on image read
Possible cause: The key-free vision channel sends images to a cloud vision service and may return 429 due to region, quota or rate limits; the channel may also be temporarily unavailable.
Fix direction: Check whether it's region / quota rate-limiting; if persistent, configure your own vision-model key per the plugin docs for a private channel; don't send sensitive screenshots through the key-free channel.
How to verify: Paste an ordinary screenshot and see if it gets parsed and answered; retry with your own key for stability.
To reproduce Source: Community plugin notes