Skip to main content
Failed updates enter built-in triage after update recovery settles. In an interactive terminal, OpenClaw shows the selected agent, saved prompt path when available, and use of your own account/tokens, then asks before launching triage. Only an affirmative Yes proceeds. Enter, n, cancellation, or no answer within 30 seconds skips the launch and preserves diagnostics and a manual recovery command. Use openclaw triage --agent codex to choose another agent. With --yes, --json, or no interactive terminal, eligible failures can start one owned automatic repair; other failures retain diagnostics and handoff commands. See automatic recovery. The original update failure and exit status remain authoritative; diagnostics do not turn a failed update into a successful one. If the update health check emits a complete lint report but does not exit before its deadline, the failure identifies that completion separately from process termination. An exited child whose output pipes remain open is reported separately. Without a complete lint report, a deadline does not establish that the checks finished. When automatic repair cannot find a usable inference route before starting a repair turn, it is recorded as skipped; the original update check remains the reported failure. In the Control UI, a failed attempt opens Ask OpenClaw with its recorded details and asks it to investigate before retrying. A lost connection or verification timeout is presented as an unknown outcome. The tab remembers the latest 32 investigated attempt identities, scoped to their Gateway and profile. Status checks, switching between those scopes, and reloading the same tab do not automatically send those investigations again. If the browser cannot read or save that history, the failure details remain visible without an automatic diagnostic request. Ask OpenClaw manually or run openclaw triage on the host. If the Gateway or agent is unavailable, use openclaw triage on the Gateway host. Automatic diagnosis keeps your unsent composer draft, including when its conversation session must restart. Control UI → Settings → Updates keeps the latest recorded attempt visible, including its time, before/after identities, reason code, failing step, and bounded diagnostic detail. A version or revision verification failure stays visible when a status check rereads the same attempt. An unknown verification outcome resolves when the expected version or revision arrives, or when the same attempt reports its final failure or cancellation. A newer recorded attempt can also replace it. Intentional cancellations, already-current installs, and updates still in progress do not start triage. For a final failed attempt, Report update failure is separate from Retry and Ask OpenClaw. It previews a bounded report containing the OpenClaw version, platform, update target, failed phase, sanitized diagnostics, and verified rollback outcome. The report excludes secrets, tokens, chat content, raw logs, private absolute paths, and recovery commands. Nothing is submitted until an administrator confirms that preview. OpenClaw then uses the existing GitHub CLI issue flow. Fallback and pending outcomes retain the sanitized report locally; a confirmed issue keeps only its durable issue URL. OpenClaw first makes a silent, read-only request with the active github.com account. A missing CLI or a failed, unavailable, or timed-out authentication check returns a prefilled issue link without starting issue creation. In the Control UI, an interrupted preparation for the recorded attempt can be retried after its local reservation expires. Once issue creation starts, a timeout, signal, nonzero exit, or malformed response without a verified issue URL leaves the attempt pending without a replay link, because the issue-creation outcome may be unknown. The action is tied to one update-attempt identity and cannot submit that attempt twice; reconnecting or refreshing status never reports it automatically. A CLI reporting error returns to the explicit action menu and never starts diagnosis on the user’s behalf. Control UI remediation uses typed product actions only. It leads with an authenticated Gateway or native action when the connected UI has the required capability and scope, preserves confirmations for disruptive operations, and keeps terminal commands as secondary host-side fallbacks. It never parses localized guidance or executes an arbitrary command string.

​
Recover in the Control UI

  1. Select Check status when the Gateway restarted, disconnected, or did not report a final result. This reads update.status; it does not start another update. Recovery controls stay disabled while the check is pending, and a rejected request appears as an error on the page or in the update dialog. The dialog shows Checking status… while waiting and Status refreshed. after a successful read, even when the recorded failure has not changed. If the Gateway is disconnected, reconnect before checking or retrying.
  2. Open View details and address the recorded failing step. Diagnostic text is bounded and redacted for display; use Gateway logs when more context is required.
  3. Select Retry update only after the cause is resolved. The Control UI uses the normal confirmed update flow and states that running sessions are interrupted while the Gateway restarts.
The controls require a connected Gateway, support for the corresponding typed Gateway method, and administrator scope. When those conditions are not met, use the CLI fallback on the Gateway host.

​
Doctor cannot enter maintenance during finalization

finalize:doctor can report Doctor could not enter maintenance when a Gateway still owns the selected state directory. A starting Gateway and a healthy serving Gateway retain that ownership for their entire process lifetime; waiting for readiness does not release the lock. Finalizers with this recovery wait for startup through the existing readiness observer. If the same holder is verified serving the installed version and build, the update finishes with a warning and leaves the Gateway running. Update history names the holder and records the skipped Doctor pass. Config and plugin maintenance remain pending. At the next maintenance window, stop that Gateway through its service or deployment owner, run openclaw update repair, then start it through the same owner. Check openclaw update status --json and openclaw gateway status --deep for the recorded warning and current health. Do not delete lock files to force entry. A dead process releases the physical lock, and lease owners reclaim provably dead identities. Unknown ownership, an unreadable database, incompatible schemas, active database writers, or unconfirmed subprocess cleanup still require their named recovery action; a maintenance warning does not authorize concurrent repair or discard recovery backups.

​
Node and global install permissions

For node-runtime-preflight, upgrade the runtime named in the message to a version satisfying both the candidate’s full engine range and the updater’s supported Node range. The suggested version is the lowest supported release in that intersection. Follow the recovery steps for the detected runtime manager (nvm, fnm, Volta, or system Node). The next step runs update through the original installation’s absolute openclaw.mjs launcher using the selected Node. It does not rely on openclaw remaining on PATH after a version-manager switch, or recommend a global install into an uninspected prefix. Extended-stable recovery uses --channel extended-stable so the resolver selects the supported monthly release; other package channels retain the inspected version with --tag. An explicit channel switch is included in recovery because the runtime refusal happens before that preference is saved. If an already-current service is stopped or its definition cannot be refreshed, have its deployment owner select the supported Node in that definition before retrying. Switching the shell runtime does not change a service’s pinned Node path. Keep the same service account, profile, and state/config overrides. Recovery restores the recorded service selectors, including overrides absent from your shell; credentials are not included. The ordinary update invocation rechecks the selected npm prefix and managed service before installation, and retains the original package owner. Its normal runtime selection, service refresh, restart, and verification checks apply. Containers redeploy the target image with the same state/config mounts. global-install-foreign-destination means the selected prefix is foreign or its ownership could not be established. An inaccessible prefix, failed npm prefix probe, or unreadable layout stops the update before staging; an unknown destination is never treated as empty. Restore inspection access or make npm prefix -g succeed with the selected runtime. Ask the deployment owner to verify unreadable layouts and explicitly select the intended installation. The report names the destination (or says that npm could not resolve it), the cause, and the selected service’s launcher when available. Switch the runtime back and retry through the retained absolute launcher. Alternatively, with the destination owner’s agreement, explicitly select that installation for the intended service using a printed gateway install --force command when available, then update. This changes the service binding; it is not permission to overwrite another deployment’s package. A protected service definition uses deployment-owner instructions instead; --force cannot replace a sealed mount. Dry-run returns the same refusal. Recorded attempts remain in update history and are shown by Doctor. If the ranges do not overlap, install a supported Node and select a compatible OpenClaw target; that candidate cannot run through this updater on a supported Node release. See Node.js. For global-install-permission-denied, check the named directory and owner. If you own the directory, the message gives a scoped chmod u+rwx command. For an administrator-owned npm prefix, have that account perform the package update or grant the intended updater write access. Keep the Gateway’s existing state and configuration; invoking the whole updater with sudo can select a different home and service account. Do not recursively change ownership of a shared system prefix. A personal install can instead use a user-writable npm prefix. Permission errors discovered after admission carry the same reason. The report’s rollback and service-recovery constraints still apply if activation had begun. Inside a container, the same next action also directs you to pull or build the target OpenClaw image and redeploy with the same state/config mounts. Package changes inside a running container are not durable.

​
Published 2026.9.4 on large agent fleets

The published 2026.9.4 updater shares a five-minute deadline across snapshot preparation and candidate checks. Its failure log tail combines output from those checks: Doctor complete. can belong to the preceding repair pass, even when lint is the failed step. The elapsed time in the final log line measures the whole rehearsal; the step duration measures the individual check. A complete lint JSON report is needed to establish that lint finished before termination. Published OpenClaw 2026.9.4 can spend many minutes preparing model catalogs and chat metadata after its HTTP listener binds. In an instrumented 480-agent control with no update, HTTP probes remained unanswered during 944 seconds of observation; the Gateway then logged ready at 947.5 seconds. Stopping that instance eventually required systemd’s existing 5-minute-30-second stop limit. These are measurements of one synthetic fixture, not expected startup budgets. A second, uninstrumented 480-agent control first passed signed Gateway handshake, serving-build, and health-RPC checks, then lost HTTP responsiveness without any update. The 25-minute post-readiness control completed; sampled failures spanned 24 minutes before a final three-minute serving check also failed. The original PID and installation remained. Shared schema 17, all 481 physical agent databases at schema 19, and config bytes stayed unchanged; captured state-maintenance leases were empty. The main thread consumed nearly one CPU core. Logs showed existing scheduled review attempts, fleet-wide integrity checks, and memory-plugin startup cleanup errors. This reproduces a published Gateway fleet preparation/background maintenance availability problem independently of updating. Its exact JavaScript hot loop remains unprofiled, and the original failed-update run lacked the live-state evidence needed to exclude an additional state or recovery defect. A retained package, PID, or serviceRestartSafe: true does not establish that the previous Gateway is serving. See the investigation. Before recovery, preserve the update report and a verified backup. Keep the same service account, profile, package manager, and installation prefix. Have that installation’s owner stop the Gateway and other writers before manual replacement. When the installed updater cannot complete, use the manual package-manager procedure with an exact target compatible with the retained state, then run the target’s openclaw doctor --fix before starting its Gateway. If the retained binary cannot read the current state, follow backup recovery; changing schema markers or deleting lease rows does not reverse migrations. Verify the actual serving version/build through an authenticated Gateway RPC and check /readyz before declaring recovery or removing backups. The plain-start control did not verify these recovery steps or establish that restarting the same 2026.9.4 fleet resolves the failed-update condition.

​
Plugin repair warnings

Doctor’s configured-plugin repair and payload-verification warnings do not block Gateway readiness. A tracked plugin whose payload is unavailable is marked unavailable, and its configuration and pending migration inputs stay preserved. This includes host-link repair failures during updates. openclaw update status --json lists pending plugin migration warnings, and Doctor reports the affected plugin and repair command. Run openclaw update repair, then openclaw doctor --fix to retry after restoring access to the plugin source. Missing configured plugins.load.paths are availability warnings. The update continues and the Gateway can become ready with the available plugins. The update report and Doctor lint identify the unavailable path with configured-plugin-path-unavailable. Permission, I/O, and other filesystem inspection failures use the distinct configured-plugin-path-inspection-failed warning with the original error code and message. For permission errors, fix permissions on the reported path, then run openclaw doctor --fix; for other failures, resolve the reported filesystem problem first. Both warnings preserve uninspected configuration and let the update continue. A load path can contain several plugins or override a bundled plugin, so discovery cannot infer which settings belong to its missing payload. Doctor preserves uninspected plugin settings, channel settings, model selections, and load-path entries instead of treating them as stale or applying another plugin’s repair. Restore the path or correct its plugins.load.paths entry, then run openclaw doctor --fix to resume inspection and repair. Other discovery errors retain their existing diagnostics. Official version-bound runtime plugins installed through ClawHub use their declared ClawHub source for the new core release cohort. The released 2026.9.4 catalog omitted that source for Codex; the correction is on main in #148518.

​
Reason codes

  • dirty, no-upstream: repair the source checkout before retrying.
  • runtime-artifact-publication: the affected Gateway is running or cannot be verified offline. Inspect openclaw gateway status --deep, stop it through its service owner, and retry. On macOS, a loaded LaunchAgent can respawn even when disabled and temporarily has no PID; openclaw gateway stop unloads it.
  • update-ledger-busy: another process held the state database’s write lock beyond the update step budget. The command exited successfully without admitting a run and left previous history intact. Retry once the Gateway’s writes settle. The update command’s JSON output contains the deferred note; openclaw update status --json shows the previous recorded run. If required finalization after a core update is deferred, its child exits nonzero so existing parents cannot mistake it for completed plugin convergence. Updated Gateways record the skipped reason and do not restart; retrying the update runs finalization again, including when the core is already current.
  • plugin-target-unavailable: an enabled configured npm plugin has no resolvable target for the selected core, or its registry metadata could not be read. The refusal identifies the plugin, package target, and registry error before the serving Gateway stops or the core package changes. Retry after publication or registry recovery, use openclaw update --tag <older-version>, or disable the affected plugin and retry. If the core version is unknown, select an exact registry version. Extended-stable rejects --tag; retry later or explicitly switch channels. --dry-run performs the same availability check.
  • preflight-insufficient-space: free space on the filesystems containing preflight staging (the checkout’s .artifacts area on POSIX) and the package-manager store, then retry. The updater stops on confirmed ENOSPC instead of trying older commits; it does not delete shared package-manager stores. See Git checkout flow for staging placement and the older published-updater limitation.
  • deps-install-failed, build-failed, ui-build-failed: inspect the failing step, fix the dependency or build error, then retry.
  • global-install-failed: the package-manager install, staging, verification, or launcher swap exited nonzero. The updater then attempts rollback. The generated report’s Rollback outcome line and openclaw update status record whether the previous install was restored and is safe to restart. openclaw gateway status --deep shows what is serving; confirm both before assuming the previous version runs. The generated failure report redacts the package manager’s own error line; the failing step’s bounded stderr tail is kept in the durable run record and in the update-failure context saved under logs/support/ in the state directory. Two causes belong to the published 2026.9.3 and 2026.9.4 updaters, and a later release cannot rescue the updater already installed: on macOS, Package rollback launcher backup changed when the updater’s umask differs from the installed launcher’s permissions, and on busy hosts or slow disks a 30-second baseline package fingerprint timeout reported as a changed package tree. Retrying with the same installed updater repeats them. Install the target once with the manual package-manager procedure, run openclaw doctor --fix, and restart the Gateway. This manual install bypasses the installed updater once. No published release contains both fixes yet: openclaw update runs through a repaired updater only after installing a release later than 2026.9.4 that contains #145282 and #144758. Other causes show the package manager’s error: EACCES, EPERM, or a prefix mismatch mean the global prefix is custom or not writable by the invoking user; fix ownership and permissions, then retry. Re-run the installer if the package install is incomplete.
  • runtime-verification-failed near 300 seconds at candidate gateway canary when updating from 2026.9.4: the installed updater shares that deadline across the snapshot and candidate checks, even with a larger --timeout. The elapsed failure duration is not Gateway startup time alone. Use the same manual package-manager procedure, then run openclaw doctor --fix and restart the Gateway. See #144858 and #154381.
  • doctor-failed: run openclaw doctor on the Gateway host, resolve its findings, then retry. See Doctor for the check list and --fix behavior.
  • restart-disabled, restart-unavailable: restore a supported supervisor or enable Gateway restarts before retrying.
  • restart-unhealthy, restart-revision-mismatch, restart-revision-unavailable: inspect Gateway service health and its install root before retrying.
  • managed-service-handoff-*: check status first. If the handoff stopped, use the CLI on the Gateway host to preserve the full diagnostic output.
Unknown reason codes remain visible. Check the Gateway logs before retrying.

​
Retained legacy session history

Invalid entries in a legacy sessions.json and malformed JSONL transcripts do not fail an update when Doctor can verify the imported SQLite state and retain the originals. Doctor skips entries without a valid session ID and imports the readable transcript prefix. It reports the file and reason as warnings in its migration report and in openclaw update status --json, including updates started by older releases that cannot record Doctor warnings themselves. While a plugin migration is pending, the original files stay in place with a verified import receipt. Repeated Doctor repairs preserve current SQLite edits and deletions. After plugin migration finishes, damaged originals remain in the protected migration archive for manual recovery; update cleanup cannot discard them as fully imported history. Preserve the named files and your pre-update backup. Inspect them with openclaw doctor --session-sqlite dry-run --session-sqlite-all-agents --json. Do not overwrite receipt-bound originals to repair them. Changed or newly appeared transcripts can contain history absent from SQLite and still block readiness. Check openclaw update status --json, stop the Gateway, and run openclaw doctor --session-sqlite recover --session-sqlite-all-agents before retrying. See session recovery.

​
CLI fallback

Run these commands on the Gateway host, not on the computer that merely has the Control UI open:
Use openclaw update --dry-run to preview a new attempt. If a package update failed after installation began, follow the installer recovery steps in Updating. If the installed CLI is damaged or the filesystem cannot write diagnostics, automatic triage reports that failure and preserves the original update error. Repair the installed command, then run openclaw triage. Managed updates retain their detached helper log even when the Gateway cannot start; the recorded outcome points to the available diagnostics or the failed collection attempt. Restart notices summarize the diagnostic outcome. Saved artifact paths and exact, installation-specific recovery commands remain in the host command output or managed update helper log rather than the notice sent to an agent or channel. If the updater crashes or is killed after the Gateway stops, the Gateway stays stopped unless the updater completed and verified recovery. Inspect openclaw gateway status --deep, repair the reported dependency or installation failure, and rerun openclaw update. A failed Git dependency install restores and rebuilds the previous runtime before allowing an automatic restart. Restarts after verified recovery still check the installed configuration, service ownership, and Gateway health.

​
Rollback boundary

Do not restore state as the first response to an update failure. First reinstall known-good code while preserving current state. Restore a verified pre-update state snapshot only when older code cannot read the current config or database. See Rollback.

​
Support diagnostics

Collect the following without posting credentials, raw config, or unredacted process output:
  • OpenClaw version and install type;
  • update timestamp, target, phase, and reason code from Settings → Updates;
  • the bounded failure detail shown by View details;
  • openclaw update status --json;
  • openclaw gateway status --deep --json;
  • relevant redacted Gateway log lines.