GuidesRunning & maintaining

OpenClaw "Doctor could not enter maintenance": the update rollback

Why an OpenClaw update rolls back on a legacy Gateway lock, what to stop before retrying, and which releases fix it on macOS and Linux.

November 20, 2026The Everpod team
The short answer

The new version’s Doctor found a Gateway lock file and could not prove its owner had stopped, so it refused to touch your state, and the update rolled back to the version you had, which keeps running. OpenClaw’s guidance is to stop the Gateway service and every other OpenClaw process using that state, check that the PID named in the message is gone, then retry. Do not delete lock files to force it. When the lock was written by a Gateway older than 2026.10.1, updates to 2026.11.5 and 2026.11.6 refuse it even when its owner is dead. As of November 20, 2026, the fix is on the main branch for macOS only and in no release; on Linux the refusal stays by design.

What the message means

The update report ends with the reason doctor-failed and a rollback line such as OpenClaw update rolled back to 2026.11.4: doctor-failed, and the Doctor output carries a message like this (the path, hash and PID are yours):

Doctor could not enter maintenance. Legacy Gateway lock /tmp/openclaw-1000/gateway.5b681173.lock still has a live or unverified owner (PID 102). Stop the Gateway service and other OpenClaw processes using this state, then run openclaw doctor --fix from an independent shell.
Copied

Before it migrates anything, the new version’s Doctor takes exclusive hold of the state directory. The update troubleshooting page says this step “can report Doctor could not enter maintenance when a Gateway still owns the selected state directory.” A lock file records which process holds the state; if Doctor cannot show that process is gone, it refuses rather than risk two programs writing at once. The update then puts the previous version back. In the report that tracks this, the rollback restored a healthy Gateway on 2026.11.4 each time, usually after under a minute of downtime.

First: stop what still holds the state

The message may be right. If a Gateway or another OpenClaw command really is running on that state, stop it, then confirm the PID from the message is gone:

openclaw gateway stop
ps -p <PID>
Copied

ps -p must print no process. On Linux, a maintainer adds, check every container that shares the same state as well, since a Gateway in another container can hold the lock while its PID means nothing on the host. Then run openclaw doctor and retry the update. The stop and restart guide covers stopping the service so it does not come straight back.

When the owner is already dead: the legacy lock

If nothing is running and the update still rolls back, you are probably in the case the issue names. The word “Legacy” in the message marks a lock record from an older Gateway. As OpenClaw’s maintainer explained on #201472: “Lock records written by Gateways older than 2026.10.1 have no processNamespace,” and OpenClaw now treats such a record “as unverifiable on every platform except Windows.” A dead PID proves nothing, so the new Doctor refuses however long ago that Gateway stopped. The reporter showed where the line falls on Linux: 2026.11.4 completed Doctor with the same file in place, and 2026.11.5 refused it every time.

Retrying does not change the outcome. On November 20 the maintainer wrote that every update to 2026.11.6 rolls back on this file “whatever version you start from”, and that the manual npm install from the update docs “does not help here either”, because it runs the same Doctor.

Which releases fix it

macOS: the fix is #201912, merged on November 19, 2026, which lets macOS updates finish past such a dead lock. In the maintainer’s words, “2026.11.6 does not contain the fix,” and it is not in 2026.11.10-beta.1 either. The issue stays open until a release carries it.

Linux: no fix is planned in that change. “Linux is unchanged on purpose,” the maintainer wrote, because a container in its own PID namespace can share the lock directory, so a missing PID on the host does not prove the owner stopped; the pull request says such a record “still needs explicit recovery.”

What you can do meanwhile

The rollback leaves the earlier version installed and serving, so the agent works as before while you wait; each further failed attempt costs another short outage while the Gateway restarts. The latest-version guide tracks which release to move to.

From 2026.11.5, OpenClaw has a supported command for a lock whose owner cannot be verified, openclaw gateway recover-lock. Its documentation at 2026.11.6 asks you to “first confirm that the recorded holder has stopped through its container or service manager”, then run the confirmation command it prints:

openclaw gateway recover-lock
openclaw gateway recover-lock --confirm <fingerprint>
Copied

It has two limits for this case. It exists only in 2026.11.5 and later, so an install that has rolled back to 2026.11.4 does not have it. And it looks only in the lock folder inside OpenClaw’s state directory: the maintainer says it “does not inspect the system temporary directory yet”, and on Linux, where the message names a path under /tmp/openclaw-<uid>/, the reporter got “No Gateway lock or owner lease is present” while Doctor kept refusing. On a Mac whose Gateway runs as a LaunchAgent, the lock sits under ~/.openclaw/tmp/openclaw-<uid>/, and the maintainer gives recover-lock as the route there from a 2026.11.5 or newer command line.

For the Linux system-temp case, a pull request to make recover-lock cover it is open and unreviewed, and the maintainer calls it “a separate maintainer decision”. The docs’ line holds meanwhile: “Do not delete lock files to force entry.” Follow the issue for the release that settles it.

Neighbouring failures

If the report shows a different refusal, such as plugin migration obligations that “changed during migration input publication”, or another phase name in its title, the update failure guide walks each phase. What openclaw doctor and --fix do on their own is in the Doctor guide.

Give your AI agents a permanent cloud computer.

We set it up and secure it, so all you do is use them. Run Claude Code, Codex or any agent you use, more at once than your laptop can hold, and keep them working when it’s closed. Or have OpenClaw set up and run for you.

See the developer pod

From $24/mo · your own plan or API key

Get your OpenClaw agent

$29/mo, cancel anytime · model usage included