"openclaw update" fails with reason code doctor-failed (update rolls back)

Exact error

Reason code: doctor-failed

Also appears as (5)

candidate doctor lint ... failed
lint: Candidate lint failed
Rollback outcome: verified safe to restart
Update history reconciliation could not complete: RangeError: Maximum call stack size exceeded
unsupported-plugin-install-index

As reported (not yet reproduced) CI: pending

Built only from official docs and public reports, linked under Sources. We have not reproduced it yet. How we verify.

Last verified: Not yet (as reported)
Published: Oct 30, 2026
Repro: None yet
Fix ID: AGT-25

Environment and versions

reported on	OpenClaw 2026.9.4 → 2026.9.5 (macOS, Node 26.8.2); 2026.9.5 → 2026.9.6 (Linux, Node 24.21.0); → 2026.10.8 (macOS, Node 26.13.0)
tested by us	not yet reproduced

In brief

The update ran OpenClaw's own checks against your state and rolled back. The full guide maps the official recovery order (what to check first, what never to delete) and the version-specific reports, with sources.

Get the full fix ↓

As reported, not yet reproduced. We have not run this failure on our test machine yet. This page is based on OpenClaw's own docs and public reports, linked under Sources. Read it as a map of what's known, not a tested fix.

Symptom

You run openclaw update (or click Update in the Control UI). It spends minutes in rehearsal or "repairing", then the update fails and rolls back. The update report (in Control UI → Settings → Updates, or the saved failure report) shows:

- Result: error
- Reason code: doctor-failed
- Rollback outcome: verified safe to restart

Reported variants include candidate doctor lint ... failed during the run (GitHub #152759), a RangeError: Maximum call stack size exceeded in update-history reconciliation (GitHub #157011), and, on the Oct 29 forum report for 2026.10.8, doctor --fix and update repair both stopping with unsupported-plugin-install-index.

Why it happens

Updates run the new version's Doctor checks before switching over. If those checks fail on your state (config, databases, plugins), the updater refuses the new version and rolls back. doctor-failed is the reason code for that.
The cause differs by release. In the reports we read, the failing check was different each time: an exec_approvals_config SQLite migration error was suspected in #152759; a stack overflow in update-history reconciliation in #157011 (it survived doctor --fix). Both issues are now closed.
Good news first: in both GitHub reports the rollback outcome was "verified safe to restart", meaning the gateway stayed on the old version.

What we could not test

Any of the reported failures. We have not reproduced them.
macOS (two of the three reports), systemd-managed gateways, and large real-world state (one report mentions a 1.1 GB agent database).

The full fix

The free part of this page tells you what's wrong. The full fix tells you exactly what to do. It includes:

Step-by-step fix, safest option first (the full page is 617 words)
1 copy-paste block of commands, config or code
How to check it worked
What the official docs say, with every claim linked (not yet reproduced by us)

Unlock this fix · $4 Every fix: $12/month

Launching soon. Checkout isn't open yet; prices may change at launch. Join the waitlist. You can check what you'll get: SHA-256 of the full fix 484970283c25bdcf… (how to check).

Sources

How this page was made

Drafted by an AI agent from the official docs and public reports listed above. Not yet reproduced on our test machine. Human review: not yet. No warranty: try fixes on a copy or staging environment first. Machine-readable versions: Markdown · JSON.

Found a mistake or a newer version where this breaks? Tell us.