OpenClaw Update Failed on a VPS? Recover or Roll Back

Published on

OpenClaw update failed on your VPS? Check whether it rolled back, match the reason code, then repair, retry or roll back to a known-good version with its CLI.

Server cabinets with mesh doors in a dark room, orange and blue cables and green status lights behind them

You ran openclaw update on your VPS and it ended badly: a failed step, a rollback message, or a Gateway that no longer answers. Before you reach for a backup, check what the updater already did; often it has put the previous version back itself. Below: how to read the outcome, the failures people reported in OpenClaw's issue tracker in late October 2026, and how to roll back on purpose. Commands come from OpenClaw's updating, rollback and CLI docs as published on 3 November 2026, the day 2026.10.10 became the stable release. It assumes the setup from our OpenClaw setup guide: Ubuntu 24.04 or Debian 12, a user named openclaw and the Gateway as a systemd user service. For port, dashboard and channel errors that have nothing to do with an update, use our OpenClaw troubleshooting guide.

Quick answer: When an OpenClaw update failed, don't restore a backup first. As the openclaw user, run openclaw update status and openclaw gateway status --deep. A run marked rolled-back means the old version is serving again: fix the reason it names and run openclaw update again. If the Gateway is down, run openclaw update repair, then openclaw doctor --fix and openclaw gateway restart. To roll back on purpose, run openclaw update --tag <version> --dry-run, then the same without --dry-run. Restore the verified backup you made before the update, together with the version that made it, only when the older version can't read the migrated state.

What openclaw update Does Before It Fails

openclaw update detects how you installed OpenClaw (npm, pnpm, Bun or git), checks the new version while the old Gateway keeps serving, then activates and verifies it. Where it stops decides what you're left with:

  • Before activation. A validation failure discards the staged version and leaves the serving Gateway untouched.
  • After activation. If the new version fails its checks, the updater can restore the previous package, command shim, service definition and exact config bytes, then restart and recheck the old Gateway. It only does this while the database schema versions are unchanged and your config still matches what the new version's Doctor wrote. The run ends as rolled-back, the headline says OpenClaw update rolled back to <previous>: <reason>, and the command still exits nonzero.
  • After a migration. Once the new version has migrated config or databases, old code alone can't undo that. The updater refuses with state-migrated-no-rollback or rollback-state-unverified and keeps the migrated state.

Step 1: Read What the Failed Update Left Behind

Switch to the OpenClaw user, as in our troubleshooting guide, and look before you change anything:

sudo -iu openclaw
export XDG_RUNTIME_DIR=/run/user/$(id -u)
openclaw --version
openclaw update status
openclaw gateway status --deep

openclaw update status shows your update channel, whether an update is available and the latest update report. With no update running, it labels that report Last recorded update with its start time. openclaw gateway status --deep shows what actually serves, which can differ from the version your shell's openclaw --version prints. For the full record, openclaw update status --json keeps the failed step and reason code under lastRun.

GitHub issues titled like Update failure: post-update-verification (2026.9.33) come from OpenClaw's own Report update failure option; the part after the colon is the failed step, followed by the version that was running. Started from the dashboard? Settings → Updates shows the same record.

Step 2: Match the Reason Code

These codes come from OpenClaw's update troubleshooting page, rollback docs and updating page:

Reason codeWhat it meansWhat to do
global-install-failed with EACCES or EPERMThe global npm folder isn't writable by the user who ran the updateSee the root-owned install section below
preflight-insufficient-spaceNot enough free disk for stagingFree space (df -h), then retry
doctor-failedThe new version's Doctor found a problemRun openclaw doctor, fix its findings, retry
plugin-target-unavailableAn enabled npm plugin has no build for the new versionRetry later, update to an older version with --tag, or disable that plugin
restart-unhealthy, restart-revision-mismatchThe restarted Gateway failed its health or version checkCheck openclaw gateway status --deep and its install root
rollback-state-unverified, state-migrated-no-rollbackRollback refused to protect migrated dataRun the repair command the report prints; see Step 3
ancestry-unverifiedThe updater couldn't verify its own process treeSee the glibc section below

In issue #183164, an update from 2026.9.33 to 2026.9.34 failed with previous-version-unverified and rolled back; a retry the next day worked. The reporter's explanation, not a confirmed cause: apt had upgraded Node.js under a Gateway running for over a week. So after apt upgrade changes Node.js, restart the Gateway before you update OpenClaw.

Step 3: Get a Stopped Gateway Back

If the updater died halfway, for example through a reboot or a killed process group, openclaw update repair is the backstop. It restores the original install when activation never started, or finishes the interrupted switch and starts the Gateway. If it answers Stop the Gateway first (openclaw gateway stop), do that and run it again. Then work through OpenClaw's after-update checklist:

openclaw update repair
openclaw status --all
openclaw update status --json
openclaw gateway status --deep
openclaw doctor --fix
openclaw gateway restart

When a handoff is pending or failed, openclaw status --all shows an Update restart line with the next command. Three cases need more:

  • An older openclaw binary refuses to manage the service. OpenClaw stamps config writes with meta.lastTouchedVersion, and an older binary won't start, stop or restart a Gateway whose config a newer version wrote. Compare which -a openclaw, openclaw --version and openclaw config get meta.lastTouchedVersion, fix your PATH so it finds the newer install, then run openclaw gateway install --force and openclaw gateway restart.
  • The unit exits with status 78 and the journal says Another gateway (pid ...) already owns this state directory. An open report on the beta line, issue #189676, describes a failed update that left a Gateway running outside its systemd unit. Find it from your admin account with sudo ss -ltnp 'sport = :18789'. If a process holds the port while systemctl --user status openclaw-gateway.service shows the unit as failed, stop that PID with kill <PID> as openclaw, then run systemctl --user start openclaw-gateway.service.
  • The Gateway looks stuck after the update. If the report says it is still starting, check its progress instead of restarting it in a loop; a prepared model runtime publication (...) timed out error names the stage it waited on. In open issue #183599, on macOS after 2026.9.6 to 2026.10.7, restarts, doctor --fix and a reboot didn't help such a Gateway; it recovered by itself about 12 hours later.

Still stuck? openclaw triage hands the recorded failure to the first coding agent it finds (Claude Code, Codex, OpenCode, then Pi) on your own account, and openclaw triage --non-interactive only collects diagnostics. Meanwhile, keep a stopped, unverified Gateway stopped and leave migrated state alone.

Root-Owned Installs: EACCES During the Update

Our setup guide, like OpenClaw's DigitalOcean guide, has root install OpenClaw with the system npm. npm puts global packages in {prefix}/lib/node_modules, and the prefix is one level above the node binary (npm folders), so with NodeSource's /usr/bin/node the package lands in /usr/lib/node_modules. Check the owner as openclaw:

npm prefix -g
ls -ld "$(npm prefix -g)/lib/node_modules/openclaw"

If it says root, openclaw update run as openclaw can't replace those files and can stop with global-install-failed and EACCES. Don't try sudo openclaw update: the docs say to keep the same service account, profile and state paths throughout. Use their manual procedure for a root-owned install, one command at a time:

# as openclaw
mkdir -p ~/Backups/openclaw
openclaw backup create --output ~/Backups/openclaw --verify
openclaw gateway stop

# from your admin account
command -v npm
npm --version
sudo /usr/bin/npm i -g openclaw@2026.10.10 --allow-scripts=openclaw

# as openclaw again
openclaw doctor --fix
openclaw gateway install --force
openclaw gateway start
openclaw gateway status --deep

--allow-scripts=openclaw needs npm 12 or npm 11.16 or newer; on npm 11.15 and older, leave it out. Use the npm path command -v npm prints, and replace the version with the one you want or the exact version a refusal message names.

Older glibc: Updates That Roll Back Every Time

Two update bugs this autumn hit hosts with a glibc older than 2.33. In September, a native helper that needed glibc 2.33 made updates on Ubuntu 20.04 fail with helper-unavailable (issue #157167); 2026.9.7 fixed that. In issue #186817, every update that needed a schema migration rolled back on a glibc 2.28 host, because the process helper failed with GLIBC_2.33' not found and the updater couldn't confirm its own process tree. PR #186871, merged on 28 October, reads that from /proc instead; it helps once the version you update to contains it, since that version's worker runs the step.

Check your host with ldd --version | head -1. Ubuntu 20.04 and Debian 11 ship glibc 2.31; Ubuntu 22.04 has 2.35, Debian 12 has 2.36 and Ubuntu 24.04 has 2.39. Below 2.33, the lasting fix is a newer OS: back up OpenClaw, reinstall the VPS with Ubuntu 24.04 and restore. If Doctor records ancestry-unverified, the docs say to make sure /proc/<pid>/stat is readable, wait for the recorded update process to exit, then run openclaw update repair.

Roll Back to a Known-Good Version

If the new version runs but misbehaves, go back through the updater, which checks compatibility and asks you to confirm the downgrade:

openclaw update --tag 2026.10.9 --dry-run
openclaw update --tag 2026.10.9

--tag applies to this update only; your saved channel still decides the next one. On the extended-stable channel, add --channel stable for an exact version, which also moves your saved channel to stable. Two limits from the rollback docs:

  • Downgrading the package doesn't reverse config or database migrations. If the older version refuses the newer state, restore your pre-update backup (next section). Don't edit meta.lastTouchedVersion or schema markers to force it.
  • A raw npm i -g keeps no previous package and skips this recovery workflow, so make a backup first when you have to use it.

For fewer surprises, switch to the extended-stable channel, a trailing release line that never updates by itself, with openclaw update --channel extended-stable. On 3 November 2026 it pointed to 2026.9.36 and latest to 2026.10.10, so from a 2026.10 version that switch is a downgrade: the updater asks you to confirm, and the two limits above apply. Versions 2026.10.9 and 2026.9.36 declare Node.js 24.22.1+ or 26.12.1+ in their package metadata, a higher floor than 2026.10.10's 24.16.0+, so check node --version before you go back to either.

Gateway automatic updates stay off unless you set update.auto.enabled, so a version stays put until you update it. If you turned them on, the docs say to set OPENCLAW_NO_AUTO_UPDATE=1 in the Gateway's environment during recovery, so it doesn't reapply the release you're backing out of; ~/.openclaw/.env is the documented place for variables the service should see.

Last Resort: Restore the Pre-Update Backup

OpenClaw's update troubleshooting page says to reinstall known-good code while keeping current state first, and to restore a verified pre-update snapshot only when older code can't read the current config or database. Then:

  1. Stop the Gateway with openclaw gateway stop and keep it stopped.
  2. Move the current ~/.openclaw aside; a restore discards everything since the backup.
  3. Install the OpenClaw version that made the archive, because the archive holds no package: sudo /usr/bin/npm i -g openclaw@<that-version> --allow-scripts=openclaw on a root-owned install.
  4. Restore the archive and move its state into place with the commands in our backup guide.
  5. Run openclaw doctor, then openclaw gateway start, and verify:
openclaw --version
openclaw health
openclaw gateway status --deep --json
openclaw doctor --lint --json
openclaw update cleanup --dry-run

Restore the config, the shared database and every agent database from one backup generation, never a mix. WhatsApp may need relinking, and plugins get their dependencies back with openclaw plugins update <id>. The last command only lists what openclaw update cleanup would remove; run it for real once everything checks out.

Before the Next Update

openclaw --version
mkdir -p ~/Backups/openclaw
openclaw backup create --output ~/Backups/openclaw --verify
node -p "process.execPath + ' ' + process.version"
df -h ~
systemctl --user is-enabled openclaw-gateway.service
openclaw update --dry-run
  • The version you write down is your known-good tag, and the archive is your full recovery point; the updater's automatic config copy and migration originals are not. Copy it off the server. Space-Node's VPS plans don't include backups in the price (you can arrange them through a ticket), and our backup guide automates the archive with restic.
  • Leave disk room. Before migrating, the updater snapshots every SQLite database next to the retained package and needs 2 × total SQLite family bytes + 3 × largest family + 64 MiB free. The plans on our AI agent VPS page have 20 to 80 GB of NVMe storage.
  • If is-enabled prints masked, run systemctl --user unmask openclaw-gateway.service, or the update refuses before it changes anything. Then read every preflight check the dry run names.

FAQ

Why does OpenClaw say the update rolled back? The new version failed a check after activation, so the updater restored the previous package, service definition and config and verified the old Gateway. The command still exits nonzero; openclaw update status names the reason.

How do I downgrade OpenClaw to an older version? Run openclaw update --tag <version> --dry-run, then without --dry-run, and confirm. If the older version can't read migrated state, restore the backup you made before the update together with its matching OpenClaw version.

Does OpenClaw update itself on a VPS? Not by default: Gateway automatic updates are off until you set update.auto.enabled: true. The extended-stable channel never applies updates automatically, even then.

Will a failed update delete my agent's sessions or memory? No. A validation failure leaves the serving Gateway untouched, and after a migration the updater keeps the migrated state plus pre-migration database snapshots. Keep every recovery path the report names until the install checks out.

Sources

All opened on 3 November 2026: