Field report: two plugins, one namespace — how dsh-pocket + dsh-web-mobile quietly broke on restart (and the 4 rules that prevent it)

[boheastill]

A field report, not a plugin release — how two well-meaning plugin installs produced a "Failed to load plugins" banner, why nothing showed in the server logs, and the four rules I now follow before touching a dsh profile. If you install community plugins, this will happen to you eventually.

The symptom

After restarting dsh web, the browser greeted me with:

Failed to load plugins
@dsh-external/dsh-mobile-nav
failed to apply loader entry (@dsh-external/dsh-mobile-nav):
locale namespace "mobileNav" already has locale "zh"

The page still loaded. The mobile nav just… wasn't there. And in journalctl --user -u dsh — nothing. Clean logs, healthy service. The failure only exists in the browser banner.

What actually happened

I was setting up mobile access and did the obvious thing:

1. dsh plugin --profile web add dsh-pocket -w — the QR-code LAN access plugin (great plugin, by the way)
2. Then, for narrow-screen layout, also: dsh plugin --profile web add github:mexiaosqwq/dsh-web-mobile — a dedicated mobile UI adaptation plugin

What I didn't know: dsh-pocket 1.13.4 has already absorbed the mobile-nav functionality upstream. Its client bundle contains NS = "mobileNav" with its own zh/en dictionaries (the source even credits client/mobile/locales.ts).

The external plugin registers the same namespace with a zh dictionary that is — word for word — the same. Bundles load in order; dsh-pocket wins, the external plugin's second registration throws already has locale "zh", and its loader entry fails.

So: two packages, one job, and a locale collision as the only visible evidence.

Why it's sneaky (the trap chain)

1. pnpm install doesn't reload anything. The running process keeps serving old code with the new profile on disk. The bomb only detonates on the next restart — which might be days later, in the middle of something else.
2. The error lives in the browser, not the journal. If you health-check via systemctl and curl, everything looks fine. "Service healthy" and "plugins loaded" are different claims.
3. The message names the symptom, not the disease. "locale namespace already has locale" reads like a translation-file bug. The actual diagnosis is duplicate functionality across two packages — you only see it by grepping who registers the namespace.

The fix

# ~/.dsh/profiles/web/package.json — remove BOTH of these:
#   dependencies["@dsh-external/dsh-mobile-nav"]
#   dsh.profile.bundles[]: "@dsh-external/dsh-mobile-nav"
cd ~/.dsh/profiles/web && pnpm install   # prunes
systemctl --user restart dsh              # or your restart path

Verification (the part everyone skips):

curl -s --noproxy '*' http://127.0.0.1:3080/ | grep -c "mobile-nav"   # must be 0
# then actually open the page in a browser and confirm the banner is gone

dsh-pocket's built-in mobile nav carries on fine; I only lost two fullscreen-preview locale keys I wasn't using anyway.

The four rules I've adopted

1. Check for absorption before adding a second plugin. Newer versions of big plugins swallow smaller ones (dsh-pocket did it to dsh-web-mobile). Before installing a dedicated plugin next to a big one:
   grep -rn 'NS = "<something>"' node_modules/<big-plugin>/client/ — if both sides register it, pick one.
2. A plugin change isn't done until restart + double check. Install → restart → browser banner check → the curl check above. "It installed without errors" is not verification; an unrestarted service is a lie about its own state.
3. Learn this error shape. locale namespace X already has locale Y = two plugins fighting over X. Not a locale bug. Trace who registers X.
4. Edit profile in both places. The dsh profile is ~/.dsh/profiles/web/package.json — dependencies AND dsh.profile.bundles must stay in sync; the CLI does it for you on add/remove, manual edits forget.

Happy to hear counter-examples or additional failure shapes — especially anything else that hides in the browser banner while the journal stays clean.

[denial123789]

I added an English plugin-audit note based on this field report: https://sandbaseai.github.io/deepseek-harness-handbook/community-plugin-audit.html

The key boundary is browser-side composition: two packages can install successfully yet collide on a locale namespace during restart. The guide now requires effective-profile inspection, clean-profile coexistence testing, and unique documented namespaces before calling a UI plugin compatible.

[boheastill]

Thanks for turning this into an audit standard — that's the right generalization:
the install step can't see runtime composition, so "coexistence testing on a clean
profile" catches what pnpm install never will.

One addition from the same incident, since your guide now covers it: the failure
was only visible in the browser banner — the journal stayed clean through all of
it. If your audit checklist has room for one more item, "confirm via the web UI,
not only logs" would have caught this class a day earlier.

[kittimzhe]

Nice field report — the "symptom vs. disease" split is exactly right. One thing worth adding from the composition side, because this is the quiet sibling of your bug:

The locale throw is one instance of a broader class: two packages claiming the same key in the composition layer. Cordis rows are keyed by id, and per the official docs "later layers win per row" — so when two bundles declare the same id, the later one silently replaces the earlier row's entire config. No banner, no "already has locale" — your config is just quietly someone else's. That's the version of this bug you never see.

Worth adding to the pre-flight checklist: inspect the effective tree, not the package.json on disk.

dsh --profile web --dump-config

--dump-config prints the tree your machine actually boots (documented in docs/user/develop/basic/publish.md and architecture.md). Grep for the bundle ids you installed and you'll see both rows composed into the tree before restart, instead of discovering the collision in the browser days later.

Same mechanism, used on purpose: my dsh-session-recall plugin overrides the official session-query-sqlite row via - id: session-query-sqlite in its cordis.patch.yml — "later wins per row" is just an override when it's intentional, and a bug when it isn't. I wrote up the composition order + the override + the --dump-config verify step here: https://github.com/kittimzhe/dsh-plugin-authoring-guide