openclaw - ✅(Solved) Fix Plugin config error causes hard gateway crash instead of graceful disable [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#60143Fetched 2026-04-08 02:35:47
View on GitHub
Comments
1
Participants
2
Timeline
5
Reactions
0
Author
Timeline (top)
referenced ×3commented ×1cross-referenced ×1

When a plugin config key is invalid (e.g. after a schema migration), the gateway throws a hard config validation error and exits with code 1 instead of disabling only the affected plugin and continuing to start.

Error Message

When a plugin config key is invalid (e.g. after a schema migration), the gateway throws a hard config validation error and exits with code 1 instead of disabling only the affected plugin and continuing to start. This single config key error (the Brave search API key was at the old path) caused the entire gateway to be unavailable for 12.5 hours and 6,198 restart attempts (see related issue #60142).

  • Plugin config errors → warn + disable plugin, do NOT exit

Root Cause

When a plugin config key is invalid (e.g. after a schema migration), the gateway throws a hard config validation error and exits with code 1 instead of disabling only the affected plugin and continuing to start.

Fix Action

Fixed

PR fix notes

PR #60171: fix: wrap plugin initialization in try/catch for graceful failure

Description (problem / solution / changelog)

Summary

Plugin register() failures no longer crash the gateway. Failed plugins are disabled for the session with a warning; all other plugins and the gateway itself continue normally.

Changes

  • Added failedAt?: Date to PluginRecord type in registry.ts
  • recordPluginError() in loader.ts now sets failedAt = new Date() when marking a plugin failed
  • After all plugins load, a startup summary is logged if any failed: [plugins] Warning: N plugin(s) failed to initialize: id1, id2. Run 'openclaw plugins list' for details.

Real incident

A single config key rename in 2026.4.1 (tools.web.search.brave moved to plugins.entries.brave) caused the gateway to refuse to start entirely, resulting in 12.5 hours of downtime.

Apr 02 20:20:46 node[2645786]: Config invalid
Apr 02 20:20:46 node[2645786]:   - tools.web.search: Unrecognized key: "brave"
Apr 02 20:20:46 systemd[332]: openclaw-gateway.service: Main process exited, status=1/FAILURE
[gateway fully offline for 12.5 hours due to single config key error]

Closes #60143

Changed files

  • src/plugins/loader.ts (modified, +14/-0)
  • src/plugins/plugin-graceful-init-failure.test.ts (added, +205/-0)
  • src/plugins/registry.ts (modified, +1/-0)

Code Example

Apr 02 20:20:46 node[2645786]: Config invalid
Apr 02 20:20:46 node[2645786]:   - tools.web.search: Unrecognized key: "brave"
Apr 02 20:20:46 systemd[332]: openclaw-gateway.service: Main process exited, code=exited, status=1/FAILURE
Apr 02 20:20:46 systemd[332]: openclaw-gateway.service: Failed with result 'exit-code'.
Apr 02 20:20:52 systemd[332]: openclaw-gateway.service: Scheduled restart job, restart counter is at 1.
RAW_BUFFERClick to expand / collapse

Description

When a plugin config key is invalid (e.g. after a schema migration), the gateway throws a hard config validation error and exits with code 1 instead of disabling only the affected plugin and continuing to start.

Real-World Incident

After upgrading from 2026.3.28 → 2026.4.1, the tools.web.search config schema changed. The old brave key path was now an unrecognized key. Instead of degrading gracefully (disabling Brave search, starting without it), the gateway rejected the entire config and refused to start.

Actual Log

Apr 02 20:20:46 node[2645786]: Config invalid
Apr 02 20:20:46 node[2645786]:   - tools.web.search: Unrecognized key: "brave"
Apr 02 20:20:46 systemd[332]: openclaw-gateway.service: Main process exited, code=exited, status=1/FAILURE
Apr 02 20:20:46 systemd[332]: openclaw-gateway.service: Failed with result 'exit-code'.
Apr 02 20:20:52 systemd[332]: openclaw-gateway.service: Scheduled restart job, restart counter is at 1.

This single config key error (the Brave search API key was at the old path) caused the entire gateway to be unavailable for 12.5 hours and 6,198 restart attempts (see related issue #60142).

Expected Behavior

Config validation errors on non-critical plugin keys should:

  1. Log a clear warning: [brave] plugin config invalid: unrecognized key "tools.web.search.brave" (moved to plugins.entries.brave.config.webSearch in 2026.4.1) — plugin disabled
  2. Disable the affected plugin for this session
  3. Allow the gateway to start and serve all other functionality

Hard exits should be reserved for truly unrecoverable errors (corrupted core config, missing required fields for critical subsystems).

Suggested Fix

In the config validation layer (src/config/ or plugin loader):

  • Distinguish between fatal config errors (core agent config corrupt) and plugin config errors (individual plugin key issues)
  • Plugin config errors → warn + disable plugin, do NOT exit
  • Add a startup summary showing which plugins were disabled due to config issues

Related

  • Caused the crash loop described in #60142
  • Config schema migration: tools.web.search.braveplugins.entries.brave.config.webSearch

Environment

  • OpenClaw: 2026.4.1
  • OS: Linux (WSL2, systemd user session)

extent analysis

TL;DR

Modify the config validation layer to distinguish between fatal config errors and plugin config errors, allowing the gateway to start even if a plugin's config is invalid.

Guidance

  • Review the config validation layer in src/config/ to identify where the hard exit is occurring and modify it to handle plugin config errors differently.
  • Implement a warning and disable mechanism for plugin config errors, rather than exiting the entire gateway.
  • Consider adding a startup summary to show which plugins were disabled due to config issues, to aid in debugging and monitoring.
  • Verify the fix by intentionally introducing a plugin config error and checking that the gateway starts and logs a clear warning, while disabling the affected plugin.

Example

No specific code example is provided, as the issue does not include enough code context, but the fix would involve modifying the config validation logic to handle plugin config errors in a more granular way.

Notes

The suggested fix assumes that the config validation layer can be modified to distinguish between fatal and non-fatal config errors, and that the plugin loader can be updated to disable plugins with invalid config without exiting the gateway.

Recommendation

Apply a workaround by modifying the config validation layer to handle plugin config errors more robustly, as upgrading to a fixed version is not mentioned as an option in the issue. This will allow the gateway to start and serve other functionality even if a plugin's config is invalid.

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