Troubleshooting
Fix a DSH plugin failed to load error
When a DSH plugin failed to load, verify installation, profile placement, module format, dependencies, and the first runtime error in that order.
01
Verify the installed artifact
Confirm the package or local path exists where the selected profile expects it and that the installed version matches the upstream instructions.
- Check the exact profile
- Inspect package metadata
- Do not guess a package name
02
Trace the loader error
Keep the first import or runtime exception and compare it with the plugin entry point. A later generic load failure is usually only a summary.
- Check ESM and CommonJS expectations
- Inspect missing peer dependencies
- Reproduce with unrelated plugins disabled
Review sources
Sources help verify current facts. Their inclusion does not imply endorsement of this page.
DSH plugin failed to load questions
What does a DSH plugin failed to load error actually mean?
It means files were resolved but the plugin never became usable. Loading additionally requires registration in the profile you started, a resolvable entry point, and dependencies present at the versions the plugin expects.
What does a module format problem look like?
Errors mentioning require is not defined, an import statement outside a module, or an unexpected token in a .js file. Those point at an ESM and CommonJS mismatch, which is a packaging problem rather than your configuration.
Can the wrong profile cause a DSH plugin failed to load error?
Frequently. A plugin installed into one profile does nothing in another and the harness will not warn you about it. Confirm which profile is active before changing anything else.
Should I reinstall to fix it?
Not as the first move. Reinstalling destroys the evidence and rarely changes the outcome, so read the first error and decide whether it is registration, resolution, or runtime.
What should I record before retrying?
The exact error text, the active profile, the working directory, and your Node and package-manager versions. Without those, the same failure looks like a brand new problem the second time around.