Plugin install troubleshooting: from error to recovery

After this tutorial you will

• Locate an install failure without repeatedly reinstalling everything
• Separate command, network, build-approval, profile, and runtime problems
• Change one variable at a time and keep a rollback path

Compatible version

Compatible with: dsh 0.1.x. Examples use the common dsh plugin --profile web add ... shape; exact error text can differ by release.

Do not reinstall yet: sort the failure into five stages

An install usually moves through command, download, build, write, and load. Identify the stage first.

Keep the raw error, install command, profile name, and system version together. “It will not install” is hard to reproduce; those four facts usually reveal the path.

Command and fetch failures

First make sure the terminal is invoking the DSH you expect. Do not upgrade Node, reinstall DSH, and edit shell configuration at the same time. Reopen a terminal, confirm DSH itself starts, then retry the original plugin command once.

For a GitHub or npm failure, inspect the source shape. github:owner/repo, an npm package name, and a local path are different inputs. Confirm the upstream repository exists in a browser, its README still documents the command, and retry only once on a stable connection. Do not force-install an archived or contradictory source.

Build scripts and allowBuilds

An error mentioning prepare, postinstall, or allowBuilds is a safety control, not a generic breakage. The safe order is:

1. Record the exact package name in the error.
2. Read why the plugin and dependency need a build step.
3. Grant approval only in the current profile for that package.
4. Re-run the same command once.
5. If it still fails, remove the approval and inspect the actual script.

Never adopt a “allow all build scripts” fix from a random snippet. Build permissions let dependencies execute code on your machine; a narrow approval is auditable and reversible.

Wrong profile and post-install failures

Many “installed but missing” reports are really installs into another profile. Compare the --profile value in the command with the web, TUI, or headless environment currently open. Do not install again until you know which profile is correct.

If installation completed but the capability does not appear, restart DSH or refresh the relevant UI, then read the README for API keys, environment variables, external binaries, or first-run setup. Validate with the smallest real task before using it in production work.

A safe repair record

Plugin: owner/repo
Profile: web
Command: dsh plugin --profile web add github:owner/repo
Symptom: package-x prepare was denied by allowBuilds
Checked: README, upstream repository, package-x purpose
Smallest repair: approve package-x only, then retry once
Result: success / failure with raw error
Rollback: revoke approval and run remove

Common questions

Why not wipe everything and reinstall?

That discards the most useful clues: the error, profile differences, and a known-good version. Make the smallest repair first; clean up only when recovery is impossible.

When should I stop troubleshooting?

Stop if you are asked to disable protections, execute shell code you cannot explain, paste a token into an unknown script, or accept a command that contradicts the README. Preserve the log and verify with upstream.

Next up

Not sure whether the plugin is worth fixing? Read How to choose DSH plugins.