fix(channels): hint at when bundled channel module is missing (#76974)

BSG2000 · Copilot · BSG2000 · web-flow · commit 98af51748d19 · 2026-05-21T21:03:49.000Z
Summary: - The PR adds a bundled-channel load-error formatter, wires it into the bundled-channel warning paths, adds focused tests, and updates the changelog. - Reproducibility: yes. source-level: current main logs bundled-channel load failures with bare `formatErrorMe ... cause`. The contributor's terminal proof demonstrates the same wrapped-error shape before and after the PR. Automerge notes: - PR branch already contained follow-up commit before automerge: fix(channels): walk error cause chain to detect missing bundled modules - PR branch already contained follow-up commit before automerge: docs(changelog): add Unreleased Fixes entry - PR branch already contained follow-up commit before automerge: Merge remote-tracking branch 'origin/main' into fix/bundled-channel-l… - PR branch already contained follow-up commit before automerge: Merge branch 'main' into fix/bundled-channel-load-doctor-hint Validation: - ClawSweeper review passed for head 416a8a2. - Required merge gates passed before the squash merge. Prepared head SHA: 416a8a2 Review: #76974 (comment) Co-authored-by: BSG2000 <github@hsu.hamburg> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: BSG2000 <BSG2000@users.noreply.github.com> Co-authored-by: BSG2000 <thomas.krohnfuss@stud.th-luebeck.de> Co-authored-by: Thomas Krohnfuß <BSG2000@users.noreply.github.com> Co-authored-by: clawsweeper[bot] <274271284+clawsweeper[bot]@users.noreply.github.com> Approved-by: takhoffman Co-authored-by: takhoffman <781889+takhoffman@users.noreply.github.com>
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -254,6 +254,7 @@ Docs: https://docs.openclaw.ai
 - Agents: guard final-delivery fresh session routing against mismatched logical sessions before reusing recovered delivery context. (#83928) Thanks @joshavant.
 - Media: prevent image metadata probing from invoking external decoder delegates on unrecognized image bytes, and stop fallback chaining after real processing errors.
 - Media: install Sharp with the root package and fall back to sips, Windows native imaging, ImageMagick, GraphicsMagick, or ffmpeg for image resizing/conversion when Sharp is unavailable. Fixes #83401. Thanks @scotthuang.
+- Channels/bundled: append `openclaw doctor --fix` guidance to the bundled-channel load warnings emitted on `ERR_MODULE_NOT_FOUND` / `MODULE_NOT_FOUND` (including those wrapped on `.cause` by the native-require loader), so users hitting unstaged plugin runtime deps (e.g. `nostr-tools`) see an actionable repair hint instead of a bare module-not-found warning. (#76974) Thanks @BSG2000.
 - Telegram: deliver generated media completions back into forum topics by preserving topic IDs across requester-agent handoff. (#83556) Thanks @fuller-stack-dev.
 - Gateway: defer update-check startup until after readiness so package update checks no longer block sidecar-ready startup, while preserving update broadcasts and shutdown cleanup. (#83520) Thanks @samzong.
 - Telegram: keep `/btw` and read-only status commands from aborting active runs, and avoid retaining raw update payloads in timed-out spool tombstones. Refs #83272.
diff --git a/src/channels/plugins/bundled-load-error.test.ts b/src/channels/plugins/bundled-load-error.test.ts
@@ -0,0 +1,52 @@
+import { describe, it, expect } from "vitest";
+import { describeBundledChannelLoadError } from "./bundled.js";
+
+describe("describeBundledChannelLoadError", () => {
+  it("appends the doctor --fix hint for a top-level MODULE_NOT_FOUND error", () => {
+    const err = Object.assign(new Error("Cannot find module 'nostr-tools'"), {
+      code: "MODULE_NOT_FOUND",
+    });
+    const detail = describeBundledChannelLoadError(err, "nostr");
+    expect(detail).toContain("Cannot find module 'nostr-tools'");
+    expect(detail).toContain("openclaw doctor --fix");
+    expect(detail).toContain("channel nostr");
+  });
+
+  it("appends the doctor --fix hint for a top-level ERR_MODULE_NOT_FOUND error", () => {
+    const err = Object.assign(new Error("Cannot find package '@larksuiteoapi/node-sdk'"), {
+      code: "ERR_MODULE_NOT_FOUND",
+    });
+    expect(describeBundledChannelLoadError(err, "feishu")).toContain("openclaw doctor --fix");
+  });
+
+  it("appends the doctor --fix hint when the missing-module code is on a nested cause (native require wrap)", () => {
+    // Mirrors src/channels/plugins/module-loader.ts which wraps require failures
+    // in `new Error(..., { cause: error })`. The MODULE_NOT_FOUND code only
+    // exists on the cause, not on the outer wrapper.
+    const inner = Object.assign(new Error("Cannot find module 'discord.js'"), {
+      code: "MODULE_NOT_FOUND",
+    });
+    const wrapped = new Error(
+      "failed to load channel plugin module with native require: /plugins/discord/index.js",
+      { cause: inner },
+    );
+    const detail = describeBundledChannelLoadError(wrapped, "discord");
+    expect(detail).toContain("openclaw doctor --fix");
+    expect(detail).toContain("channel discord");
+    // The detail should still surface the underlying message via the existing
+    // formatErrorMessage cause traversal.
+    expect(detail).toContain("Cannot find module 'discord.js'");
+  });
+
+  it("returns the bare detail when the error is unrelated", () => {
+    const detail = describeBundledChannelLoadError(new TypeError("boom"), "whatsapp");
+    expect(detail).not.toContain("openclaw doctor --fix");
+    expect(detail).toContain("boom");
+  });
+
+  it("does not loop on a self-referential cause chain", () => {
+    const err = new Error("outer") as Error & { cause?: unknown };
+    err.cause = err;
+    expect(() => describeBundledChannelLoadError(err, "msteams")).not.toThrow();
+  });
+});
diff --git a/src/channels/plugins/bundled.ts b/src/channels/plugins/bundled.ts
@@ -1,6 +1,6 @@
 import path from "node:path";
 import type { OpenClawConfig } from "../../config/types.openclaw.js";
-import { formatErrorMessage } from "../../infra/errors.js";
+import { extractErrorCode, formatErrorMessage } from "../../infra/errors.js";
 import { isPathInside } from "../../infra/path-guards.js";
 import { createSubsystemLogger } from "../../logging/subsystem.js";
 import type {
@@ -241,6 +241,35 @@ function loadGeneratedBundledChannelModule(params: {
   }
 }
 
+// Walk the `.cause` chain looking for a Node-style "module not found" code.
+// Native-require failures inside `module-loader.ts` rewrap the original Node
+// error in a new Error with `{ cause }`, so the missing-module code lives on
+// the cause rather than the top-level error.
+function findMissingModuleCodeInChain(error: unknown): string | undefined {
+  const seen = new Set<unknown>();
+  let current: unknown = error;
+  while (current && !seen.has(current)) {
+    seen.add(current);
+    const code = extractErrorCode(current);
+    if (code === "ERR_MODULE_NOT_FOUND" || code === "MODULE_NOT_FOUND") {
+      return code;
+    }
+    if (typeof current !== "object") {
+      return undefined;
+    }
+    current = (current as { cause?: unknown }).cause;
+  }
+  return undefined;
+}
+
+export function describeBundledChannelLoadError(error: unknown, channelId: string): string {
+  const detail = formatErrorMessage(error);
+  if (findMissingModuleCodeInChain(error) !== undefined) {
+    return `${detail} (run \`openclaw doctor --fix\` to install missing bundled runtime dependencies for channel ${channelId})`;
+  }
+  return detail;
+}
+
 function loadGeneratedBundledChannelEntry(params: {
   rootScope: BundledChannelRootScope;
   metadata: BundledChannelPluginMetadata;
@@ -264,7 +293,7 @@ function loadGeneratedBundledChannelEntry(params: {
       entry,
     };
   } catch (error) {
-    const detail = formatErrorMessage(error);
+    const detail = describeBundledChannelLoadError(error, params.metadata.manifest.id);
     log.warn(`[channels] failed to load bundled channel ${params.metadata.manifest.id}: ${detail}`);
     return null;
   }
@@ -293,7 +322,7 @@ function loadGeneratedBundledChannelSetupEntry(params: {
     }
     return setupEntry;
   } catch (error) {
-    const detail = formatErrorMessage(error);
+    const detail = describeBundledChannelLoadError(error, params.metadata.manifest.id);
     log.warn(
       `[channels] failed to load bundled channel setup entry ${params.metadata.manifest.id}: ${detail}`,
     );
@@ -573,7 +602,7 @@ function getBundledChannelPluginForRoot(
     loadContext.lazyPluginsById.set(id, normalizedPlugin);
     return normalizedPlugin;
   } catch (error) {
-    const detail = formatErrorMessage(error);
+    const detail = describeBundledChannelLoadError(error, id);
     log.warn(`[channels] failed to load bundled channel ${id}: ${detail}`);
     loadContext.lazyPluginsById.set(id, null);
     return undefined;
@@ -601,7 +630,7 @@ function getBundledChannelSecretsForRoot(
     loadContext.lazySecretsById.set(id, secrets ?? null);
     return secrets;
   } catch (error) {
-    const detail = formatErrorMessage(error);
+    const detail = describeBundledChannelLoadError(error, id);
     log.warn(`[channels] failed to load bundled channel secrets ${id}: ${detail}`);
     loadContext.lazySecretsById.set(id, null);
     return undefined;
@@ -626,7 +655,7 @@ function getBundledChannelAccountInspectorForRoot(
     loadContext.lazyAccountInspectorsById.set(id, inspector);
     return inspector;
   } catch (error) {
-    const detail = formatErrorMessage(error);
+    const detail = describeBundledChannelLoadError(error, id);
     log.warn(`[channels] failed to load bundled channel account inspector ${id}: ${detail}`);
     loadContext.lazyAccountInspectorsById.set(id, null);
     return undefined;
@@ -654,7 +683,7 @@ function getBundledChannelSetupPluginForRoot(
     loadContext.lazySetupPluginsById.set(id, plugin);
     return plugin;
   } catch (error) {
-    const detail = formatErrorMessage(error);
+    const detail = describeBundledChannelLoadError(error, id);
     log.warn(`[channels] failed to load bundled channel setup ${id}: ${detail}`);
     loadContext.lazySetupPluginsById.set(id, null);
     return undefined;
@@ -682,7 +711,7 @@ function getBundledChannelSetupSecretsForRoot(
     loadContext.lazySetupSecretsById.set(id, secrets ?? null);
     return secrets;
   } catch (error) {
-    const detail = formatErrorMessage(error);
+    const detail = describeBundledChannelLoadError(error, id);
     log.warn(`[channels] failed to load bundled channel setup secrets ${id}: ${detail}`);
     loadContext.lazySetupSecretsById.set(id, null);
     return undefined;
