Home / internal / hermes-skills / hermes-dashboard-plugin-troubleshooting.md

Skill: hermes-dashboard-plugin-troubleshooting

Hermes dashboard plugin troubleshooting

Use this when the Hermes web dashboard shows errors like: - COULD NOT LOAD THIS PLUGIN’S SCRIPT - plugin tab exists but opening it fails - /dashboard-plugins/... requests 404 or behave inconsistently

Goal

Separate three different failure classes before changing any proxy or public access settings: 1. Local dashboard/plugin registry problem 2. Reverse-proxy/subpath problem 3. Intentional access-control block

Do not fix this class of issue by widening public access unless the user explicitly asks for that.

Workflow

  1. Check local dashboard first against 127.0.0.1:9119.
  2. Query /api/dashboard/plugins
  3. Check the plugin script path locally

  4. If the dashboard is mounted under a subpath, send X-Forwarded-Prefix matching that subpath

  5. Compare advertised plugins vs real scripts.

  6. If /api/dashboard/plugins lists plugin NAME, verify:
    • /dashboard-plugins/NAME/dist/index.js
    • optional CSS path from plugin metadata

  7. If metadata advertises a plugin but its local script is 404, the problem is a stale/broken plugin registration, not public networking.

  8. Verify local routes before touching Caddy.

  9. /
  10. /api/dashboard/plugins
  11. /dashboard-plugins/<name>/dist/index.js

  12. relevant SPA route such as /example or /kanban

  13. Only then inspect public behavior.

  14. 403 on every /kanban/* route usually means allowlist/access-control
  15. 404 publicly while local works usually means proxy/routing mismatch
  16. mixed 404/plugin errors can still come from a bad plugin advertised by the local registry

Fix patterns

A. Advertised plugin has no local script

Symptom pattern: - /api/dashboard/plugins includes plugin NAME - local /dashboard-plugins/NAME/dist/index.js returns 404

Fix: - disable that plugin locally instead of exposing more routes - common safe method for local optional plugins: disable/remove/rename its dashboard manifest so it is no longer advertised - restart hermes-dashboard.service - re-check /api/dashboard/plugins and confirm the broken plugin disappeared

B. Local works, public /kanban/* blocked

That is an access-control/proxy issue, not a dashboard build issue. Do not claim the plugin path is broken until local checks fail too.

C. Dashboard service broken after updates

If the service itself will not start, rebuild the web frontend first, then restart the service. See references/rebuild-and-example-plugin-404.md.

Verification checklist

After any fix: - dashboard service is active (running) - plugin registry no longer advertises broken plugins - needed plugin script returns 200 locally - intended dashboard SPA route returns 200 locally - if public access is supposed to stay restricted, confirm no access widening was introduced

Session-specific references