The update said it succeeded. The Gateway says otherwise. Here are the nine startup failures people actually hit after an OpenClaw update, matched to the exact log line each one prints, with the fix and the rollback for each.
openclaw update finishes. It prints a version number. You go to send a message and nothing answers. openclaw gateway status says stopped, or says running with the port closed, or the log is a wall of the same three lines every sixteen seconds because launchd keeps restarting a process that keeps dying.
This happens often enough that the project's own troubleshooting runbook has a section titled "After an update." What that runbook doesn't do is walk you through each distinct failure with the log signature that identifies it. That's this post. Find your log line, jump to its section, skip the rest.
The first sixty seconds, in order
Before diagnosing anything, run the official command ladder. It fixes a surprising share of post-update breakage on its own and surfaces the log line you need for the rest.
openclaw status --all
openclaw update status --json
openclaw gateway status --deep
openclaw doctor --fix
openclaw gateway restart
Then read the logs. openclaw logs --follow is the preferred path. If the Gateway won't stay up long enough to serve logs, go to the files: /tmp/openclaw/openclaw-YYYY-MM-DD.log by default, ~/.openclaw/logs/gateway.err.log on a macOS LaunchAgent install, or journalctl --user -u openclaw-gateway.service -n 200 --no-pager on Linux systemd.
If the Gateway is healthy after doctor --fix and a restart, you're done. If not, match the log to one of the nine below.
An update that prints "success" has only proven that npm finished. Whether the files on disk are complete, the config still validates, and the service came back up are three separate questions.
1. ERR_MODULE_NOT_FOUND pointing at a file in dist/
The log: Cannot find module '.../node_modules/openclaw/dist/<something>.js'
What happened: the install is incomplete. The clearest documented case was the 2026.4.24 npm release, where a postinstall step timed out (spawnSync /usr/bin/node ETIMEDOUT in the install output) and silently pruned 1,617 of the package's 4,116 dist files on Linux. The update reported success. The Gateway then failed on every start because the modules it imported no longer existed, and plugin runtime directories held symlinks pointing at nothing.
The fix: don't try to repair the tree. Reinstall cleanly, and if the current version is the problem, pin the last known good one.
openclaw gateway stop
npm install -g openclaw@<previous-version>
openclaw doctor --fix
openclaw gateway restart
Verify with ls node_modules/openclaw/dist | wc -l before and after if you want to see the difference. If reinstalling the current version keeps losing files, the postinstall is timing out on your machine; a slow disk or a starved container will do it. Pin, wait for the next release, and read the how to update OpenClaw guide's section on staged updates before trying again.
2. The update ran while the Gateway was still running (macOS)
The log: varies, but the shape is "crash immediately after openclaw update," often with module or JSON parse errors on files that look fine a minute later.
What happened: on macOS, openclaw update has historically run npm's file replacement while the LaunchAgent still had the old process holding those files open. npm can't cleanly overwrite files a live Node process has mapped, launchctl kickstart -k then restarts against a half-written tree, and you get a Gateway that dies on boot. Issue #66390 documents it as consistent across versions.
The fix: stop the service yourself before updating, then start it yourself after.
launchctl unload ~/Library/LaunchAgents/ai.openclaw.gateway.plist
openclaw update --no-restart
launchctl load ~/Library/LaunchAgents/ai.openclaw.gateway.plist
The September 2026.9.2 release improved this path (Gateway restarts after Git updates are restored, and chat-triggered updates now report success, failure, or skip with recovery guidance), but stop-then-update remains the safe habit on any supervised install.
3. Invalid config, Unrecognized key, or config validation failed
The log: Gateway rejected invalid config on startup, or hot-reload logs saying it skipped an invalid edit.
What happened: the config schema moved and your openclaw.json didn't. A key that was valid last month is unknown now, or a new key was written by the update that an older component can't read. This is also the classic post-rollback failure: newer releases add plugin entries (2026.4.24 added plugins.entries.feishu and plugins.entries.whatsapp) that require that version or later, so if you downgrade, the config still references them and the older Gateway refuses to boot.
The fix:
openclaw config file
openclaw config validate
openclaw doctor --fix
config validate names the offending key. doctor --fix removes or migrates known drift, including cleaning out those version-gated plugin entries after a rollback. If you edited the file by hand, remember it's JSON5; a trailing comma or comment that was fine before a parser change can be the whole problem. The config validation failed decoder covers the specific key errors.
4. Tight crash loop with an unhandled promise rejection
The log: the same stack trace every ten to twenty seconds, ending in an unhandled rejection from a plugin or subsystem. The documented case is [plugins] bonjour: watchdog detected non-announced service followed by CIAO ANNOUNCEMENT CANCELLED, on 2026.4.24, Apple Silicon.
What happened: a watchdog restarted the mDNS advertiser when it stayed in "announcing" past about eight seconds. The cancellation surfaced as a rejected promise nobody was awaiting, the process died, launchd restarted it, and the loop repeated every sixteen seconds. Downgrading fixed it instantly.
The fix: this class of bug is version-specific, and the honest fix is to go back one version until the patch lands.
npm i -g openclaw@<previous-version>
openclaw doctor --fix
openclaw gateway restart
Run doctor --fix after the downgrade, not before, so it can strip the config keys the newer version wrote (see section 3). Then check the release notes and issue tracker for your exact log line before you try the new version again.
5. The process dies with no error, and dmesg says OOM
The log: nothing useful in the Gateway log. journalctl or dmesg shows the kernel's OOM killer taking the process, often during "sidecar startup" right after boot.
What happened: newer releases start more at boot (sidecars, plugin runtimes, embedding caches), and on a small Linux box the startup spike exceeds available memory. The OOM killer stops the process, systemd or npm restarts it immediately with no delay, the same spike hits again, and you have an infinite loop that looks like a crash but is actually a resource ceiling. Reported on Ubuntu 24 npm installs from 2026.4.24 onward.
The fix: confirm it first, because it's easy to misdiagnose.
dmesg -T | grep -i "killed process"
journalctl --user -u openclaw-gateway.service -n 200 --no-pager | grep -i oom
Then either give the box more memory, add swap as a stopgap, or add a restart delay to the systemd unit so the loop can't spin. Disable plugins you don't use; each one adds startup memory. The OpenClaw OOM errors post has the sizing numbers.
6. EADDRINUSE or "Port 18789 is already in use"
The log: exactly that, or gateway status says running while the connectivity probe fails.
What happened: two things think they own the port. The most common post-update version is a split-brain install: the update put a new openclaw somewhere, the supervisor is still pointing at the old one, and both try to bind. The docs call it out by name.
The fix: find the duplicate, then reinstall the service from the install you actually want.
which -a openclaw
openclaw --version
openclaw gateway status --deep
openclaw gateway install --force
openclaw gateway restart
which -a showing two paths is your answer. If you changed gateway.port at any point, the supervisor unit keeps the old port until doctor --fix or gateway install --force rewrites it. The port 18789 in use decoder handles the non-update variants.
7. protocol mismatch after a rollback
The log: protocol mismatch ... client=... min= max= expected=, repeating, after you downgraded.
What happened: the old Gateway is running fine. A newer client process (a dashboard, an editor integration, a long-running openclaw logs --follow shell, an app-server helper) is still trying to reconnect with a protocol range the older Gateway can't speak. The Gateway isn't broken; it's correctly refusing a client from the future.
The fix: openclaw gateway status --deep lists established clients with PIDs and command lines. Stop or restart the one whose command line points at the newer install. Restart any apps that embed OpenClaw. Do not try to make the old Gateway accept the new protocol; the version gate is there to stop exactly the corruption you're avoiding.
8. Plugin load failure after a partial upgrade
The log: plugin ... failed to load, a plugin blocked by dangerous-code scanning during the update, or a plugin referencing an SDK alias that no longer exists.
What happened: plugins update on their own schedule, and an update can leave one of them referencing core modules that moved. Two documented shapes: plugin updates failing with ERR_MODULE_NOT_FOUND against a dist file while core was mid-update (2026.4.9 on macOS), and, from September 8, 2026, the removal window opening for deprecated untrusted-named prompt-context aliases in the Plugin SDK. A plugin that never migrated to the channel-named fields and buildChannelMetadata can stop loading on a current core.
The fix: disable the failing plugin, get the Gateway up, then deal with the plugin.
openclaw doctor --fix
# if a specific plugin is named in the log, disable it in openclaw.json and restart
openclaw gateway restart
2026.9.2 added repair of retired plugin install configuration before service startup and stopped warning about intentionally disabled plugins, so on a current version this section is shorter than it used to be. Check the plugin's own changelog for a compatible release; the ClawHub skills security audit post covers what to do when the blocker is the dangerous-code scan rather than a missing module.
The variant doctor --fix cannot repair. If the Gateway loops without ever reporting ready and the log points at plugin install metadata, you have the conflict tracked as issue #108528: the startup migration finds one plugin recorded differently in the legacy plugins/installs.json and the newer shared SQLite plugin index, and refuses to continue. doctor --fix does not reconcile the two. This is the failure behind the reports of people running the repair eleven times in a row; the pass count was never the problem. Reconcile it by hand, letting the SQLite index win:
openclaw gateway stop
mv ~/.openclaw/plugins/installs.json ~/.openclaw/plugins/installs.json.bak
openclaw plugins install <plugin-id>
openclaw gateway restart
If the plugin used to be built in, it is not missing, it moved. WhatsApp, Discord, Brave, Perplexity and roughly twenty other channel and provider extensions became external @openclaw/* packages at 2026.5.2, and the migration installed none of them automatically (issue #77483). A config that still references one produces a failed load on every start. Reinstall the ones you actually use, then let doctor --fix clear the references you do not:
openclaw plugins install @openclaw/whatsapp
openclaw doctor --fix
Non-interactive shells are where this bites twice. Installing a plugin that needs capability consent cannot prompt, so it fails in a script or a provisioning run unless you grant consent explicitly:
openclaw plugins install clawhub:<package> --accept-capabilities
openclaw plugins update <plugin-id> --accept-capabilities
Bundled and verified first-party plugins do not need the flag. Third-party ones do, and Perplexity is the one people trip over, because it ships as its own plugin (@openclaw/perplexity-plugin) rather than a provider you can simply configure. A config naming Perplexity on a host where that plugin was never installed and consented to will keep failing its load every start. Our plugin externalization breakdown lists everything that moved.
9. Runtime: stopped and "no service," or "refusing to bind gateway without auth"
The log: gateway status reports no supervised service at all, or the last gateway error mentions refusing to bind without auth.
What happened: the update rewrote or dropped the supervisor config (launchd plist, systemd unit, scheduled task), or your gateway.bind is non-loopback and the update's stricter defaults now refuse to start without an auth token configured.
The fix:
openclaw gateway install --force
openclaw gateway restart
# Linux user services: survive logout
sudo loginctl enable-linger "$USER"
For the auth refusal, either keep gateway.bind on loopback and reach the host over SSH (ssh -N -L 18789:127.0.0.1:18789 user@host), or set gateway.auth.mode and gateway.auth.token and restart. Also watch for Gateway start blocked: set gateway.mode=local if a remote mode is set without the expected local stamp; the OpenClaw gateway guide explains the modes.
How to roll back without making it worse
Rollback is fine. Rolling back badly causes sections 3 and 7. The order that works:
- Stop the service first, on every platform.
- Install the previous version with an explicit pin.
- Run
openclaw doctor --fixafter the downgrade so it strips config the newer version wrote. - Start the service.
- Run
openclaw gateway status --deepand kill any client still pointing at the newer install.
And before the next update, take the backup that makes every section above survivable. Three commands, thirty seconds:
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.$(date +%F)
cp -r ~/.openclaw/state ~/.openclaw/state.$(date +%F)
openclaw --version > ~/.openclaw/last-known-good.txt
That last line is the one everyone skips and then needs at 2am. Our safe update process covers the full routine and the four checks worth running afterwards.
Take that config copy before you run doctor --fix, not after. Users report the repair path pruning config keys it does not recognise, occasionally taking provider credentials parked in a field the current schema no longer knows about. The official doctor documentation does not describe this behaviour either way, so treat it as reported rather than specified, and keep the copy you took thirty seconds ago.
Then read the release notes for defaults that changed (2026.9.2 flipped two, covered in the 2026.9.2 update breakdown), and update at a time when you can afford ten minutes of the Gateway being down. If you run agents for other people, "update on Friday at 6pm" is how you meet section 5 on a Saturday.
On which version to land on: as of publication, ClawStat.us rates 2026.9.3 "skip" on 23 credible blocking issues with no fix release available, and points people at 2026.9.1 instead. If you are on 9.1 and stable, staying there is a defensible choice this cycle rather than a failure to keep up.
We built BetterClaw's managed hosting because we hit every one of these nine on our own Gateways over the first six months. Updates are staged, the service is stopped and restored around them, config is migrated before restart, and if a release breaks your agent it rolls back automatically. Free plan, bring your own keys.
What the nine have in common
Look at them again and it's really three problems wearing nine coats. Files on disk don't match the version the Gateway thinks it is (1, 2, 6, 8). Config on disk doesn't match the schema the Gateway expects (3, 4's rollback path, 9). Or the process is fine and something around it isn't: memory (5), a stale client (7), a missing supervisor (9).
That's why the ladder works so often. doctor --fix reconciles config drift, gateway install --force reconciles the supervisor, and a clean pinned install reconciles the files. When you know which of the three you have, the fix is rarely more than four commands. When you don't, you end up deleting things at 2am. Read the log line first.
If any of this resonated, give BetterClaw a try. Free plan with 1 agent and 100 credits a month, bring your own API keys, no inference markup. Pro is $49 a month for 5 agents. OpenClaw-compatible agents with updates you don't have to babysit. Start free or see full pricing.
Frequently Asked Questions
What does it mean when the OpenClaw gateway won't start after an update?
It almost always means one of three things: the installed files don't match the version (an incomplete npm install, or an update that ran while the old process still held the files), the config on disk no longer validates against the new schema, or something around the process failed such as memory, a stale client, or a missing supervisor entry. The log line identifies which; openclaw doctor --fix followed by openclaw gateway restart resolves a large share of the config and supervisor cases.
How does rolling back OpenClaw compare to reinstalling the current version?
Reinstall first if the log shows a missing module or an incomplete tree, since that's usually a bad install rather than a bad release. Roll back when the failure is a version-specific crash loop (an unhandled rejection from a subsystem, for example) that the previous version didn't have. After any rollback, run openclaw doctor --fix to strip config keys the newer version wrote, and check gateway status --deep for stale clients causing protocol mismatch.
How do I find the OpenClaw gateway logs when it won't stay running?
Use openclaw logs --follow if the Gateway runs at all. Otherwise read the files directly: /tmp/openclaw/openclaw-YYYY-MM-DD.log by default, ~/.openclaw/logs/gateway.err.log for a macOS LaunchAgent install, and journalctl --user -u openclaw-gateway.service -n 200 --no-pager on Linux systemd. For a suspected OOM loop, dmesg -T | grep -i "killed process" is the confirming signal.
Is it worth running openclaw update on a production Gateway?
Yes, but not casually. Stop the service before updating on macOS (the update has historically run while the LaunchAgent held files open), back up openclaw.json and the state directory, read the release notes for changed defaults, and update when a ten-minute outage is acceptable. Pin the previous version's number somewhere you can find it at 2am.
Is openclaw doctor --fix safe to run when the gateway is down?
Yes; it's the fourth rung of the project's own post-update ladder and is designed to run against a stopped Gateway. It migrates config drift, cleans version-gated plugin entries after a rollback, rewrites stale supervisor metadata such as a changed port, and reports the last gateway error from the logs. It won't repair an incomplete install; for missing dist/ files, reinstall or pin a version instead. Two caveats the documentation does not cover: users report it pruning config keys it does not recognise, so copy openclaw.json before running it, and it does not reconcile a legacy plugins/installs.json that conflicts with the shared SQLite plugin index, which is the one crash loop that repeat passes will never clear.
