Troubleshooting plugins

Most plugin problems come from a handful of repeatable causes: a missing manifest, a layer-order conflict, or a bad module reference. Work through them in the order below.

The plugin does not show up in the verify output

Confirm the layer first:

dsh --profile default --dump-config

If the plugin's # == <package-name> layer is missing, the package almost certainly lacks a dsh.bundle manifest and installed as a plain dependency. Rather than guess, paste the package name into the publish check — it runs the same rule the indexer uses and reports exactly what the manifest is missing.

Two plugins conflict on the same layer

When two bundles patch the same rows, the later bundle in the profile wins and replaces the row's whole configuration. If behaviour broke after adding a second plugin, check the bundle order in your profile first. Then remove one of the two to confirm it is the cause:

dsh plugin remove <package-name>

The plugin errors at boot

Read the dsh log output first — it names the failing module. Then open the bundle's cordis.patch.yml and check that the module it references actually exists in the package (right name, right entry point). To isolate the problem, remove the plugin from the profile and boot again: if boot is clean, the plugin is the cause.

The install itself fails

Install failures are usually mundane. Confirm the npm package name is exactly right (the listing's copy-ready command is the safest source), then check network access from the machine running the install. The install forwards to the package manager, so its error messages apply as-is.

Clean reinstall

When a plugin is stuck in a broken half-state, remove and reinstall it:

dsh plugin remove <package-name>
dsh plugin add <package-name>

This drops both the dependency and the layer, then reinstalls the latest version from scratch.