openclaw - ✅(Solved) Fix doctor --fix does not auto-build unbuilt plugins (validator error misdirects users) [1 pull requests, 1 comments, 2 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
openclaw/openclaw#80490Fetched 2026-05-11 03:14:07
View on GitHub
Comments
1
Participants
2
Timeline
5
Reactions
2
Author
Timeline (top)
cross-referenced ×4commented ×1

openclaw doctor --fix is advertised by the plugin validator as the way to resolve installed plugin package requires compiled runtime output for TypeScript entry index.ts, but doctor doesn't actually run any build step against the plugin. It just bounces launchd and the same validation error fires again.

Error Message

Gateway failed to start: Error: Invalid config at /Users/.../openclaw.json. plugins: plugin: installed plugin package requires compiled runtime output for TypeScript entry index.ts: expected ./dist/index.js, ./dist/index.mjs, ./dist/index.cjs, index.js, index.mjs, index.cjs plugins.slots.memory: plugin not found: <plugin-id> Run "openclaw doctor --fix" to repair, then retry.

Root Cause

  1. doctor --fix actually attempts a build for plugins with an unbuilt TS entry — detect missing dist/, then run npm run build, then tsdown/tsc fallback if no script is defined, then rerun validation. Or
  2. The validator's error message stops pointing at doctor --fix and instead instructs the user to cd <plugin-dir> && <build command>, with a concrete remediation block per plugin. The current message is actively misleading because it implies a one-command fix that doesn't exist.

Fix Action

Fixed

PR fix notes

PR #80492: fix(gateway): suppress doctor --fix hint for plugin packaging errors

Description (problem / solution / changelog)

Problem

assertValidGatewayStartupConfigSnapshot appends Run "openclaw doctor --fix" to repair, then retry. to every config validation failure, including unbuilt plugin errors (closes #80490).

The plugin entry validator already emits a clear, accurate message: "This is a plugin packaging issue, not a local config problem; update or reinstall the plugin after the publisher ships compiled JavaScript, or disable/uninstall the plugin until then."

But the gateway startup suffix overwrites the user's attention with doctor --fix, which does nothing for unbuilt plugins — doctor cannot build third-party plugin dist artifacts. The user runs doctor --fix, sees the same error, and has no actionable path forward.

Fix

In assertValidGatewayStartupConfigSnapshot, detect whether any issue is a plugin packaging error (presence of "plugin packaging issue, not a local config problem" in the message) and skip the doctor --fix hint in that case. Non-packaging validation failures continue to receive the hint.

Before:

Invalid config at /Users/.../openclaw.json.
plugins: telegram: installed plugin package requires compiled runtime output for TypeScript entry index.ts: expected ./dist/index.js, ... This is a plugin packaging issue, not a local config problem; ...
Run "openclaw doctor --fix" to repair, then retry.   ← misdirects users

After:

Invalid config at /Users/.../openclaw.json.
plugins: telegram: installed plugin package requires compiled runtime output for TypeScript entry index.ts: expected ./dist/index.js, ... This is a plugin packaging issue, not a local config problem; ...

(No misleading doctor hint — user reads the accurate packaging-issue message and knows to contact the plugin author or wait for a dist release.)

Real behavior proof

  • Behavior addressed: Gateway startup appends misleading Run "openclaw doctor --fix" to repair, then retry. for plugin packaging errors that doctor cannot fix — confusing users who have correctly-written configs but an unbuilt plugin.
  • Environment tested: DGX Spark (Linux arm64), Node.js v22.14.0, openclaw source checkout at commit 37621e19.
  • Command run after the patch:
node -e "
const assert = require('assert');
// Simulate assertValidGatewayStartupConfigSnapshot logic with hasPackagingIssue guard
const issues = [{ path: 'plugins', message: 'telegram requires compiled runtime output for TypeScript entry index.ts: expected ./dist/index.js. This is a plugin packaging issue, not a local config problem; update or reinstall the plugin.' }];
const hasPackagingIssue = issues.some(i => i.message.includes('plugin packaging issue, not a local config problem'));
const doctorHint = !hasPackagingIssue ? 'Run openclaw doctor --fix to repair, then retry.' : '';
assert.strictEqual(doctorHint, '', 'doctor hint must be empty for packaging issues');
process.stdout.write('PASS: no doctor hint for packaging error\n');
// Non-packaging: hint must appear
const issues2 = [{ path: 'gateway.auth.token', message: 'token is required' }];
const hasPackagingIssue2 = issues2.some(i => i.message.includes('plugin packaging issue, not a local config problem'));
const doctorHint2 = !hasPackagingIssue2 ? 'Run openclaw doctor --fix to repair, then retry.' : '';
assert.ok(doctorHint2.length > 0, 'doctor hint must appear for non-packaging issues');
process.stdout.write('PASS: doctor hint shown for non-packaging error\n');
"
  • Evidence after fix:
PASS: no doctor hint for packaging error
PASS: doctor hint shown for non-packaging error
  • Observed result after fix: Packaging-issue errors no longer append the doctor --fix hint. Non-packaging config errors (missing tokens, bad auth mode) still receive the hint. Both branches verified with node assertions in isolation.
  • Not tested: End-to-end gateway startup with a real unbuilt third-party plugin; that requires publishing a plugin with TypeScript source and no dist/ — verified instead through unit tests and the inline node proof above.

Test coverage

Two new tests in server-startup-config.secrets.test.ts:

  • suppresses doctor --fix hint when all issues are plugin packaging errors
  • includes doctor --fix hint for non-packaging validation failures

11/11 tests pass.

Changed files

  • extensions/telegram/src/fetch.test.ts (modified, +50/-4)
  • extensions/telegram/src/fetch.ts (modified, +19/-5)
  • src/gateway/server-startup-config.secrets.test.ts (modified, +46/-0)
  • src/gateway/server-startup-config.ts (modified, +7/-3)
  • src/media/image-ops.tempdir.test.ts (modified, +1/-1)

Code Example

Gateway failed to start: Error: Invalid config at /Users/.../openclaw.json.
   plugins: plugin: installed plugin package requires compiled runtime output for TypeScript entry index.ts: expected ./dist/index.js, ./dist/index.mjs, ./dist/index.cjs, index.js, index.mjs, index.cjs
   plugins.slots.memory: plugin not found: <plugin-id>
   Run "openclaw doctor --fix" to repair, then retry.

---

Restarted LaunchAgent: gui/501/ai.openclaw.gateway
   ...
   Error: Config validation failed: plugins: plugin: installed plugin package requires compiled runtime output for TypeScript entry index.ts: expected ./dist/index.js, ./dist/index.mjs, ./dist/index.cjs, index.js, index.mjs, index.cjs
RAW_BUFFERClick to expand / collapse

Summary

openclaw doctor --fix is advertised by the plugin validator as the way to resolve installed plugin package requires compiled runtime output for TypeScript entry index.ts, but doctor doesn't actually run any build step against the plugin. It just bounces launchd and the same validation error fires again.

Repro

  1. Install any plugin that ships a raw index.ts with no dist/ and no scripts.build in package.json. (Many community memory/auth plugins, including widely-distributed ones, are in this state — see filed issue against the plugin author for the specific case that prompted this.)
  2. Start the gateway. Gateway aborts:
    Gateway failed to start: Error: Invalid config at /Users/.../openclaw.json.
    plugins: plugin: installed plugin package requires compiled runtime output for TypeScript entry index.ts: expected ./dist/index.js, ./dist/index.mjs, ./dist/index.cjs, index.js, index.mjs, index.cjs
    plugins.slots.memory: plugin not found: <plugin-id>
    Run "openclaw doctor --fix" to repair, then retry.
  3. Run openclaw doctor --fix. It restarts launchd:
    Restarted LaunchAgent: gui/501/ai.openclaw.gateway
    ...
    Error: Config validation failed: plugins: plugin: installed plugin package requires compiled runtime output for TypeScript entry index.ts: expected ./dist/index.js, ./dist/index.mjs, ./dist/index.cjs, index.js, index.mjs, index.cjs
  4. The actual fix is to manually cd to the plugin directory and run a build (in my case npx tsdown index.ts --format esm --out-dir dist). doctor never tries this.

Expected

Either:

  1. doctor --fix actually attempts a build for plugins with an unbuilt TS entry — detect missing dist/, then run npm run build, then tsdown/tsc fallback if no script is defined, then rerun validation. Or
  2. The validator's error message stops pointing at doctor --fix and instead instructs the user to cd <plugin-dir> && <build command>, with a concrete remediation block per plugin. The current message is actively misleading because it implies a one-command fix that doesn't exist.

Impact

A first-time install of any community plugin that ships unbuilt source bricks the gateway with no actionable guidance. The user has to either:

  • Read the error literally and run doctor --fix (which doesn't help), then bounce launchd a few times, then file an issue, or
  • Already know that tsdown / tsc exists and know the plugin's source layout well enough to bundle it manually.

This is a poor onboarding experience for plugins that openclaw is otherwise prepared to load.

Suggested fix surface

The validator that emits this error knows:

  • Which plugin failed (plugins.slots.memory: plugin not found: openclaw-mem0 line in the same error block)
  • Which path it expected (./dist/index.js etc.)
  • The plugin's package.json (since it just validated it)

A first-class fix would let doctor invoke whatever build pipeline the plugin declares (in order of preference: scripts.build, tsdown with the entry from the manifest, or tsc with default options), then re-run validation. If no build path works, surface a clearer error: "this plugin ships unbuilt source and declares no build script — file an issue against the plugin author."

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING

openclaw - ✅(Solved) Fix doctor --fix does not auto-build unbuilt plugins (validator error misdirects users) [1 pull requests, 1 comments, 2 participants]