OpenClaw "Update failure: <phase>": what it means and the fix
What package-swap, package-update, candidate-doctor and the other phases mean, where the error the report hides is, and how to get past each one.
“Update failure: <phase> (<version>)” is the title of the report OpenClaw’s updater writes when an update fails and someone chooses “Report update failure”. The phase is the last step that failed and the version is the one that was installed, not the target. In most of these reports nothing changed: the line “Recovery outcome: verified serving” with the old version means the agent kept running on it. The real error is not in the public report, which shows [redacted-diagnostic]; it is on the machine, in openclaw update status --json and the saved report. Read it, fix that cause, and if the phase is one the installed updater keeps failing at, install the target once with the package manager.
Where these issues come from
After a failed openclaw update in a terminal, or a failed update from Settings → Updates in the Control UI, OpenClaw offers to diagnose the failure, to report it, or to exit. “Report update failure” shows a sanitized issue body and, once you confirm, files it on OpenClaw’s tracker. The title is built in the updater’s report code as Update failure: <phase> (<version>), where the phase is the public name of the last failed step. More than 750 issues titled this way were opened between October 1 and November 18, 2026. Runs with --yes, --json or no terminal never file one, according to the update command’s docs.
The body redacts private paths, commands and most error text, so the line that matters usually reads Failing check package-swap (Error): [redacted-diagnostic]. That is why maintainers reply to most of these issues by asking for the local status output. The fields worth reading in your own copy:
- Failed phase is the step in the title. Several “Failed phase” lines under Bounded diagnostics show every step that failed.
- Reason code is the class of failure:
global-install-failedfor any of the install, stage, verify or swap steps,doctor-failedfor Doctor,candidate-snapshot-failed, and so on. The update troubleshooting page lists what each one asks of you. - Recovery outcome says what was running when the updater finished: “verified serving 2026.9.8”, “verified safe to restart”, or “not serving”.
First: is the agent still running?
Most of these failures stop before the new version is switched in, and the updater puts back the previous version when a check after the switch fails. A maintainer’s reply to one report puts it plainly: “Your Gateway is still serving 2026.9.8, and the update stopped before it swapped any files.” Check before doing anything else, on the machine that runs the agent:
openclaw --version
openclaw gateway status --deep
openclaw update statusCopiedIf the Gateway is running on the old version, there is no hurry: the agent works as it did, and the update can wait until the cause is fixed. If it is stopped, that is the gateway-recovery-verification case below. Do not delete lock files or the updater’s recovery files to get it going; the troubleshooting page is explicit that dead processes release their locks.
Where the real error is
Three places on the machine hold what the public report hid:
openclaw update status --jsoncarries the last run (lastRun) with each step, its status and its detail. A maintainer gave this command to print only the failed steps:
openclaw update status --json | node -e 'let t="";process.stdin.on("data",c=>t+=c).on("end",()=>{const r=JSON.parse(t).lastRun;console.log(JSON.stringify((r?.steps||[]).filter(s=>s.status==="failed").map(s=>({step:s.step,detail:s.detail})),null,2))})'Copied- The Markdown report whose path the update prints when it finishes, kept in the
update-reportsfolder of OpenClaw’s state directory (~/.openclawby default). - Settings → Updates → View details in the Control UI, which keeps the latest attempt with its reason code, failing step and bounded detail.
Run them as the same user that owns the installation. Do not run the update again just to produce the error a second time: the saved attempt is the evidence maintainers ask for, and a rerun adds another failed run to the history.
What each phase was doing, and the way past it
The names come from the updater’s step list at 2026.11.5. The causes are the ones maintainers and reporters established in the issues, as of November 18, 2026; the detail from your own status output decides which applies.
package-update
The whole package update as the installed updater runs it. The recent reports come from installs on 2026.10.10, 2026.11.1 and 2026.11.2, with reason unexpected-error or global-install-failed. The known cause on those releases is Could not determine whether backup files are SQLite databases with spawnSync … ETIMEDOUT: their updater checks the state folder’s files for SQLite databases within one 10-second limit, and a state folder with many files runs past it (#193962). The fix is in 2026.11.3 and later, but the update is always run by the updater you already have, so it cannot reach you through openclaw update. The maintainers’ way past it is one manual install with the package manager; the OpenClaw latest-version guide carries the exact command for each release. Another reason code in the same phase is global-install-permission-denied (#200720): a directory of the installation that the updating user cannot write. The troubleshooting page says to fix that directory’s owner or permissions, not to run the updater under sudo or change ownership of a shared prefix recursively.
package-install and package-install-omit-optional
The npm install of the new version. When the first try (package-install) fails, the updater tries again leaving out optional dependencies, so a title naming package-install-omit-optional means both tries failed. In most of these reports the npm error is [openclaw] error: this OpenClaw release requires Node >=24.22.1 <25 || >=26.12.1., the Node requirement of 2026.10.6 to 2026.10.9. Update Node, check that the Gateway service uses the new one (openclaw gateway status --deep shows its path), and run the update again; which Node version OpenClaw needs has the table. For ETARGET, E404 or EINTEGRITY, the troubleshooting page points to npm cache verify and your registry or mirror.
package-swap
The swap of the installed package for the new one, with the reason global-install-failed. In the reports on the tracker the old version was still serving afterwards. The causes found so far:
EACCESorEPERM: the install directory or its prefix belongs to another user. Fix the ownership, as above.- “Package publication recovery permissions are unsafe”, reported on installs from 2026.9.8 on: an earlier update left its finished activation journal with a second hard link, and every later update refuses it (#187468). The troubleshooting page: let any updater process finish, run
openclaw doctor --fixfrom the affected installation, then retry, and do not delete the journal or loosen permissions. - “The selected package recovery executable changed after runtime preflight”: the Node binary changed while the update ran, as when Homebrew upgrades Node at the same moment (#171636). The reporter got past it with the manual install below and
openclaw update repair.
candidate-state-snapshot
A copy of your state taken so the new version can be tried against it without touching the original (labelled “Preparing update checks”), reason candidate-snapshot-failed. A maintainer notes that the code “names the phase”, not a cause. The cause seen most is SQLite worker queue capacity reached on large state (#179516, #195362). The snapshot is taken by the installed updater, so a fix in the target does not help, and the troubleshooting page says openclaw update repair cannot finish a snapshot that never completed. The way past it is the manual install below.
candidate-doctor
The new version’s Doctor run against that copy, a rehearsal of its data migrations (labelled “Checking data migrations”), reason doctor-failed. In these reports the old version stays installed and serving. The causes vary by release: from 2026.11.4 to 2026.11.5, a false Cold transcript archive … is missing or unreadable (#200594, fixed on the main branch after 2026.11.5, where a maintainer called staying on 2026.11.4 safe); on a hop from 2026.9.8, a plugin migration check (reported in #187468). Run openclaw doctor on the installed version to see its findings, and match the detail from the status output against the open reports in the latest-version guide before retrying.
candidate-gateway-startup
A trial start of the new version’s Gateway against the copy (labelled “Checking Gateway startup”), failing check startupz, reason runtime-verification-failed. The new Gateway did not come up: OpenClaw’s updating docs name plugin loading, port conflicts, migrations and readiness timeouts as the causes its reports record. One cause from the tracker: secrets that the Gateway needs at startup, read from 1Password through an exec SecretRef, fail with “required secrets are unavailable” because the trial copy has no credentials/ folder (#192066; the fix was in no release when the maintainers last wrote, and moving those secrets to the built-in store provider got the reporter past it). The startup error itself is in the failed step’s detail.
gateway-recovery-verification
The updater’s last check that a Gateway answers after the attempt, whatever happened before it. This is the phase where the agent can be down: the recovery outcome reads “not serving” or “recovery check failed (gateway-probe-failed)”. In many of these the update had been handed to the service that runs the Gateway and the handoff failed (managed-service-handoff-failed), as happens with updates started from the Control UI. Check openclaw gateway status --deep. If the Gateway is not running, a maintainer called openclaw update repair “the supported recovery” and safe to run; run it from a terminal as the installation’s owner, then check status again. On stable 2026.9.6 to 2026.9.9 and 2026.10.1 to 2026.10.5, console logging at debug alone makes this handoff fail; set logging.consoleLevel to info for the update.
update
The update as a whole, named when the failure came from the update request rather than one of its steps. The recent ones are updates requested through the Gateway (the Control UI’s button, or the update.run call), with the reason update-recovery-pending and a failed managed-service-handoff step. The troubleshooting page’s advice for a handoff failure is to check status first, in Settings → Updates or with openclaw update status and openclaw gateway status --deep, and then to run openclaw triage or the update from a terminal on the Gateway’s machine.
global-install-failed and doctor-failed
Titles with a reason code in place of a step come from updaters on 2026.9.4 and earlier, and their bodies say almost nothing more. The troubleshooting page names two bugs in the 2026.9.3 and 2026.9.4 updaters, fixed in 2026.9.5, and says to install the target once by hand, as below; for doctor-failed, run openclaw doctor first and resolve what it finds.
The one-time manual install
When the fault is in the installed updater, the maintainers’ route in OpenClaw’s update methods replaces it for one hop. Make a verified backup first, then run each line only after the previous one succeeds, as the same user and with the same package manager and prefix:
openclaw gateway stop
npm i -g openclaw@2026.11.5 --allow-scripts=openclaw
openclaw doctor --fix
openclaw gateway install --force
openclaw gateway start
openclaw gateway status --deepCopiedLeave out --allow-scripts=openclaw on npm 11.15 and earlier, and in a shell with no terminal, such as a script, openclaw gateway stop needs --force. Later updates run through the new updater, with its fixes. If you need to go back afterwards, the rollback and downgrade guide covers what an older version can still read; the general order of a safe update is in how to update OpenClaw.
On a server nobody is watching
An update run from a cron job, a script, or with --yes never offers the report or the repair menu. It exits with a nonzero status on a failed, pending or rolled-back outcome, saves its diagnostics to ~/.openclaw/logs/support/openclaw-update-failure-<id>.json (readable by the owner only), and prints a command for later:
openclaw triage --run --update-result <path>CopiedThat command starts a coding agent (Claude Code, Codex, OpenCode or Pi, whichever is found first) on your own account to diagnose and repair the installation, so run it in a terminal when you can watch it. A job that updates on a schedule should test the exit status and tell you, since an agent left on the old version keeps working and gives no other sign.