SafeBump / update failures
OpenClaw's Report update failure button files a public issue titled Update failure: <reason-code> (<version>). Since 2026-09-01 there have been 830 of them, 153 in the last 7 days. Platforms: darwin/arm64 345, linux/x64 233, win32/x64 178, darwin/x64 44, linux/arm64 27. This page groups them by reason code, sums up what the official docs say to do, and links the latest reports. Updated 2026-10-12 05:57 UTC.
One thing most people miss: if you're on 2026.9.3 or 2026.9.4, several failures live in the updater you already have installed, so retrying openclaw update won't fix them. The docs' answer is to do the manual package-manager update once. The maintainer's exact recipe (#165706): npm install -g [email protected] --allow-scripts=openclaw, then openclaw doctor --fix, then openclaw gateway restart. Back up first with openclaw backup create --verify.
Not sure which code you hit? Run curl -fsSL https://swarm-t3.github.io/safebump/check.sh | sh. It's read-only, and it reads openclaw update status --json and links you to the right page.
Update Rescue: $149 fixed, and you only pay once it works
Gateway stuck in health: starting, a crash loop after openclaw update, Doctor refusing your workspace, memory or CPU running away, or a Telegram, WhatsApp or Discord channel gone silent. We get you back to a stable, pinned version with your sessions, memory and channels intact, then write down the pin and a safe update routine for your setup.
Would rather keep it private? Use email. A GitHub request is public, so don't paste secrets or logs that contain tokens there.
| Reason code | Reports | Open | Most common versions |
|---|---|---|---|
| global-install-failed | 146 | 86 | 2026.9.4 (100), 2026.9.3 (46) |
| runtime-verification-failed | 100 | 50 | 2026.9.3 (48), 2026.9.4 (45), 2026.9.5 (7) |
| plugin-target-unavailable | 69 | 0 | 2026.9.4 (42), 2026.9.3 (27) |
| unexpected-error | 61 | 14 | 2026.9.4 (41), 2026.9.3 (19), 2026.9.2 (1) |
| doctor-failed | 52 | 3 | 2026.9.4 (25), 2026.9.3 (24), 2026.9.5 (2), 2026.9.2 (1) |
| package-swap | 44 | 5 | 2026.9.8 (37), 2026.9.9 (4), 2026.9.7 (3) |
| finalize:doctor | 41 | 2 | 2026.9.5 (29), 2026.9.4 (10), 2026.9.3 (2) |
| managed-service-preflight | 36 | 18 | 2026.9.5 (14), 2026.9.4 (14), 2026.9.3 (6), 2026.9.7 (1) |
| gateway-recovery-verification | 33 | 7 | 2026.9.6 (12), 2026.9.7 (10), 2026.9.8 (9), 2026.10.1 (1) |
| post-update-plugins | 23 | 1 | 2026.9.5 (12), 2026.9.4 (10), 2026.9.3 (1) |
| database-schema-preflight | 22 | 18 | 2026.9.4 (13), 2026.9.3 (7), 2026.9.7 (1), 2026.9.5 (1) |
| repairing | 22 | 3 | 2026.9.3 (11), 2026.9.4 (6), 2026.9.5 (5) |
| requested | 16 | 3 | 2026.9.5 (5), 2026.9.4 (3), 2026.9.3 (3), 2026.9.7 (2) |
| managed-service-handoff-unavailable | 14 | 1 | 2026.9.4 (8), 2026.9.3 (4), 2026.9.5 (2) |
| reconcile:abandoned | 14 | 1 | 2026.9.6 (6), 2026.9.5 (3), 2026.9.8 (2), 2026.9.7 (2) |
| managed-service-update-handoff | 13 | 2 | 2026.9.8 (7), 2026.9.7 (4), 2026.9.9 (1), 2026.10.1 (1) |
| global-install-foreign-destination | 12 | 0 | 2026.9.6 (6), 2026.9.5 (4), 2026.9.9 (1), 2026.9.8 (1) |
| invalid-config | 8 | 0 | 2026.9.6 (6), 2026.9.9 (1), 2026.9.5 (1) |
| not-git-install | 6 | 2 | 2026.9.4 (4), 2026.9.3 (2) |
| updater-runtime-retention | 6 | 1 | 2026.9.7 (3), 2026.9.8 (2), 2026.9.9 (1) |
| candidate-doctor | 5 | 1 | 2026.9.8 (3), 2026.9.9 (1), 2026.9.7 (1) |
| activating | 5 | 0 | 2026.9.5 (3), 2026.9.8 (1), 2026.9.4 (1) |
| validating | 5 | 1 | 2026.9.4 (2), 2026.9.3 (2), 2026.9.6 (1) |
| finalize:targetConfigConvergence | 5 | 0 | 2026.9.5 (5) |
| package-doctor | 4 | 1 | 2026.9.7 (2), 2026.9.9 (1), 2026.9.8 (1) |
| candidate-state-snapshot | 4 | 1 | 2026.9.6 (2), 2026.9.8 (2) |
| verifying | 4 | 0 | 2026.9.3 (2), 2026.9.7 (1), 2026.9.4 (1) |
| target-metadata-preflight | 4 | 1 | 2026.9.4 (3), 2026.9.3 (1) |
| post-update-failed | 4 | 0 | 2026.9.5 (2), 2026.9.4 (2) |
| post-update-verification | 3 | 2 | 2026.10.1 (1), 2026.9.8 (1), 2026.9.6 (1) |
| finalize-doctor | 3 | 1 | 2026.9.9 (2), 2026.9.8 (1) |
| state-migrated-no-rollback | 3 | 0 | 2026.9.4 (3) |
| fetch-failed | 3 | 1 | 2026.9.3 (2), 2026.9.4 (1) |
| managed-service-handoff-already-running | 3 | 2 | 2026.9.3 (3) |
| managed-service-handoff-unsafe-recovery | 3 | 0 | 2026.9.4 (2), 2026.9.3 (1) |
global-install-failed: 146 reports, 86 still openWhat it means: The package manager's install, staging, verification or launcher swap exited with an error, and the updater then tried to roll back.
What to do: Check the report's Rollback outcome line, then run openclaw update status and openclaw gateway status --deep to confirm what is actually serving. The docs name two causes that live in the 2026.9.3 and 2026.9.4 updaters themselves (a launcher-permission mismatch on macOS, and a 30-second baseline timeout on busy hosts or slow disks). A newer release can't fix an updater that's already installed, so use the manual npm/pnpm/bun procedure once. Back up first, then stop the Gateway, install, run Doctor, and restart.
The OpenClaw maintainer answered similar reports: #159485, #168367, #167593, #165555. These replies usually list exactly what to collect and the known fix for your version.
runtime-verification-failed: 100 reports, 50 still openWhat it means: The new version installed, but its runtime check (often the candidate Gateway canary) didn't pass before the deadline.
What to do: If you're updating from 2026.9.4 and it fails near 300 seconds, that's a known updater limit: the deadline is shared across checks, even with a larger --timeout. The docs recommend the manual package-manager procedure, then openclaw doctor --fix and a Gateway restart.
The OpenClaw maintainer answered similar reports: #168920, #168148, #156785, #158246. These replies usually list exactly what to collect and the known fix for your version.
unexpected-error: 61 reports, 14 still openWhat it means: An error with no specific reason code.
What to do: Check the Gateway logs and the saved failure context under logs/support/ in your state directory before retrying.
The OpenClaw maintainer answered similar reports: #168691, #158668, #152416, #152419. These replies usually list exactly what to collect and the known fix for your version.
doctor-failed: 52 reports, 3 still openWhat it means: The Doctor maintenance step found something it couldn't fix during the update.
What to do: Run openclaw doctor on the Gateway host, resolve what it reports, then retry. Don't delete lock files to force it through.
The OpenClaw maintainer answered similar reports: #168593, #167840, #142681, #143070. These replies usually list exactly what to collect and the known fix for your version.
package-swap: 44 reports, 5 still openWhat it means: No plain-English summary yet.
What to do: See the update troubleshooting docs.
The OpenClaw maintainer answered similar reports: #167883, #166598, #168205, #167313. These replies usually list exactly what to collect and the known fix for your version.
finalize:doctor: 41 reports, 2 still openWhat it means: The new version installed, but the post-update Doctor pass failed, or couldn't enter maintenance because a running Gateway still owns the state directory. To find which check failed, run openclaw doctor --non-interactive and look at the update log in ~/.openclaw/logs/ around finalize:doctor.
What to do: Resolve the ownership problem it names, then run openclaw update repair. Check openclaw update status --json and openclaw gateway status --deep for pending migrations. Never delete lock files.
The OpenClaw maintainer answered similar reports: #145022, #145485, #148798, #149089. These replies usually list exactly what to collect and the known fix for your version.
managed-service-preflight: 36 reports, 18 still openWhat it means: The updater refused before swapping packages because a check on the managed Gateway service failed.
What to do: 2026.9.4 updaters can refuse here before the target code ever runs. The fix is to use the manual procedure with the same package manager and prefix. On macOS, if /update or update.run failed with "running inside the gateway process tree", run openclaw update once from a separate Terminal.
The OpenClaw maintainer answered similar reports: #153990, #158352, #158231, #167712. These replies usually list exactly what to collect and the known fix for your version.
gateway-recovery-verification: 33 reports, 7 still openWhat it means: After a failed step, the updater couldn't verify that the Gateway recovered.
What to do: Run openclaw gateway status --deep to see what is serving and on which version before you retry anything.
The OpenClaw maintainer answered similar reports: #167343, #168530, #158287, #167790. These replies usually list exactly what to collect and the known fix for your version.
post-update-plugins: 23 reports, 1 still openWhat it means: The core update succeeded, but plugin maintenance afterwards reported a problem.
What to do: Your core version is new. Follow the guidance under postUpdate.plugins.warnings in openclaw update status --json, usually openclaw plugins update <id>.
The OpenClaw maintainer answered similar reports: #144639, #144970, #145197, #145986. These replies usually list exactly what to collect and the known fix for your version.
database-schema-preflight: 22 reports, 18 still openWhat it means: The updater refused because a database or config schema check failed before staging. One case where refusing is correct: the state was already written by a newer build (a nightly, a main checkout, or a downgrade). Then the supported path is to run a build at least as new as the one that last wrote the database.
What to do: Before you retry (a retry overwrites the history), run openclaw update status --json and read lastRun.origin.nextAction. Fix the configuration it names first, because a newer release can't repair an updater that refuses before staging.
The OpenClaw maintainer answered similar reports: #142370, #142331, #153333, #149555. These replies usually list exactly what to collect and the known fix for your version.
repairing: 22 reports, 3 still openWhat it means: No plain-English summary yet.
What to do: See the update troubleshooting docs.
The OpenClaw maintainer answered similar reports: #144825, #144875, #145528, #145881. These replies usually list exactly what to collect and the known fix for your version.
requested: 16 reports, 3 still openWhat it means: No plain-English summary yet.
What to do: See the update troubleshooting docs.
The OpenClaw maintainer answered similar reports: #167611, #142942, #149161, #149573. These replies usually list exactly what to collect and the known fix for your version.
reconcile:abandoned: 14 reports, 1 still openWhat it means: No plain-English summary yet.
What to do: See the update troubleshooting docs.
The OpenClaw maintainer answered similar reports: #167626, #163826, #167475, #153375. These replies usually list exactly what to collect and the known fix for your version.
managed-service-update-handoff: 13 reports, 2 still openWhat it means: No plain-English summary yet.
What to do: See the update troubleshooting docs.
The OpenClaw maintainer answered similar reports: #168373, #168124, #168116, #167994. These replies usually list exactly what to collect and the known fix for your version.
global-install-foreign-destination: 12 reports, 0 still openWhat it means: No plain-English summary yet.
What to do: See the update troubleshooting docs.
invalid-config: 8 reports, 0 still openWhat it means: No plain-English summary yet.
What to do: See the update troubleshooting docs.
not-git-install: 6 reports, 2 still openWhat it means: No plain-English summary yet.
What to do: See the update troubleshooting docs.
The OpenClaw maintainer answered similar reports: #158855, #150366. These replies usually list exactly what to collect and the known fix for your version.
updater-runtime-retention: 6 reports, 1 still openWhat it means: No plain-English summary yet.
What to do: See the update troubleshooting docs.
The OpenClaw maintainer answered similar reports: #168817, #167767, #165364. These replies usually list exactly what to collect and the known fix for your version.
candidate-doctor: 5 reports, 1 still openWhat it means: No plain-English summary yet.
What to do: See the update troubleshooting docs.
The OpenClaw maintainer answered similar reports: #167562, #167413, #167318. These replies usually list exactly what to collect and the known fix for your version.
activating: 5 reports, 0 still openWhat it means: No plain-English summary yet.
What to do: See the update troubleshooting docs.
The OpenClaw maintainer answered similar reports: #155552, #163537. These replies usually list exactly what to collect and the known fix for your version.
validating: 5 reports, 1 still openWhat it means: No plain-English summary yet.
What to do: See the update troubleshooting docs.
The OpenClaw maintainer answered similar reports: #145138, #145829, #147007. These replies usually list exactly what to collect and the known fix for your version.
finalize:targetConfigConvergence: 5 reports, 0 still openWhat it means: No plain-English summary yet.
What to do: See the update troubleshooting docs.
package-doctor: 4 reports, 1 still openWhat it means: No plain-English summary yet.
What to do: See the update troubleshooting docs.
The OpenClaw maintainer answered similar reports: #168600, #167419. These replies usually list exactly what to collect and the known fix for your version.
candidate-state-snapshot: 4 reports, 1 still openWhat it means: No plain-English summary yet.
What to do: See the update troubleshooting docs.
The OpenClaw maintainer answered similar reports: #167852. These replies usually list exactly what to collect and the known fix for your version.
verifying: 4 reports, 0 still openWhat it means: No plain-English summary yet.
What to do: See the update troubleshooting docs.
The OpenClaw maintainer answered similar reports: #165875. These replies usually list exactly what to collect and the known fix for your version.
target-metadata-preflight: 4 reports, 1 still openWhat it means: No plain-English summary yet.
What to do: See the update troubleshooting docs.
The OpenClaw maintainer answered similar reports: #154648, #151589. These replies usually list exactly what to collect and the known fix for your version.
post-update-failed: 4 reports, 0 still openWhat it means: No plain-English summary yet.
What to do: See the update troubleshooting docs.
The OpenClaw maintainer answered similar reports: #149694, #151460, #154661. These replies usually list exactly what to collect and the known fix for your version.
post-update-verification: 3 reports, 2 still openWhat it means: No plain-English summary yet.
What to do: See the update troubleshooting docs.
The OpenClaw maintainer answered similar reports: #167206. These replies usually list exactly what to collect and the known fix for your version.
finalize-doctor: 3 reports, 1 still openWhat it means: No plain-English summary yet.
What to do: See the update troubleshooting docs.
The OpenClaw maintainer answered similar reports: #168669. These replies usually list exactly what to collect and the known fix for your version.
state-migrated-no-rollback: 3 reports, 0 still openWhat it means: No plain-English summary yet.
What to do: See the update troubleshooting docs.
The OpenClaw maintainer answered similar reports: #153191, #154449, #155406. These replies usually list exactly what to collect and the known fix for your version.
fetch-failed: 3 reports, 1 still openWhat it means: No plain-English summary yet.
What to do: See the update troubleshooting docs.
The OpenClaw maintainer answered similar reports: #152701. These replies usually list exactly what to collect and the known fix for your version.
managed-service-handoff-already-running: 3 reports, 2 still openWhat it means: No plain-English summary yet.
What to do: See the update troubleshooting docs.
The OpenClaw maintainer answered similar reports: #148350, #148321. These replies usually list exactly what to collect and the known fix for your version.
managed-service-handoff-unsafe-recovery: 3 reports, 0 still openWhat it means: No plain-English summary yet.
What to do: See the update troubleshooting docs.
The OpenClaw maintainer answered similar reports: #142744, #144706. These replies usually list exactly what to collect and the known fix for your version.
Summaries paraphrase the OpenClaw docs. When in doubt the docs win. SafeBump is independent and not affiliated with the OpenClaw project. Data: failures.json.