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

- Fix ID: AGT-25
- Exact error: `Reason code: doctor-failed`
- Status: As reported (not yet reproduced) (CI: pending, no CI results exist yet)
- Last verified: not yet (as reported)
- Platforms: OpenClaw
- 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
- Repro: none yet
- Canonical: https://stucktoshipped.com/fixes/openclaw/update-doctor-failed/

## 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.

> **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).

## Full fix (paid)
The step-by-step fix, commands and test record are paid content and are not in this file. Price: $4 per fix (planned launch price; checkout not open yet). SHA-256 of the full fix: 484970283c25bdcf10e0e53e77f337973697f8a2efdd9ba7218a55452bcdc3c2. How to buy: https://stucktoshipped.com/pricing/ and https://stucktoshipped.com/products.json

## Sources
- [OpenClaw docs: Update troubleshooting (reason codes, incl. doctor-failed)](https://docs.openclaw.ai/install/update-troubleshooting)
- [GitHub #152759: update 2026.9.4 → 2026.9.5 fails with reason code doctor-failed; auto-rollback succeeds (closed)](https://github.com/openclaw/openclaw/issues/152759)
- [GitHub #157011: managed update 2026.9.5 → 2026.9.6 always rolls back (survives doctor --fix) (closed)](https://github.com/openclaw/openclaw/issues/157011)
- [OpenClaw Community forum: Update to 2026.10.8 failed, stuck between database migration and Doctor errors (Oct 29, 2026)](https://community.openclaw.ai/t/update-to-2026-10-8-failed-stuck-between-database-migration-and-doctor-errors/266)
- [GitHub search: issues with "update" and "doctor" in the title since Sep 1, 2026](https://github.com/openclaw/openclaw/issues?q=is%3Aissue+in%3Atitle+update+doctor+created%3A%3E%3D2026-09-01)

## How this page was made
Drafted by an AI agent from official docs and public reports. Not yet reproduced. No warranty; test on a copy first.