openclaw - 💡(How to fix) Fix [Bug]: Gateway hangs at plugins.bootstrap on 2026.4.26 (never reaches ready) [1 comments, 2 participants]

Summary

On 2026.4.26 image, openclaw gateway hangs before reaching ready, with no log output after starting.... The hang is inside prepareGatewayPluginBootstrap — the next-expected startupTrace.measure("plugins.bootstrap", ...) call never completes, so port 18789 is never listened on and /healthz is unreachable.

This is distinct from related issues:

• #73874 — that gateway reaches ready and binds; ours never reaches ready.
• #73411 — that hangs at "starting channels and sidecars..."; ours hangs much earlier.
• #73353 — that's a 60s sidecars.channels hang; ours is a permanent plugins.bootstrap hang.
• #74630 (meta) — fits the broader 4.24-4.26 regression cluster.

A rebuild of the local image from main HEAD (post-4.26 commits) eliminates the hang. So the fix is presumably already merged; this issue documents the reproducible signature for users still on the 2026.4.26 image and adds the diagnostic recipe.

Environment

• Windows host + Docker Desktop (WSL2 backend)
• Image: 2026.4.26
• Compose: stock docker-compose.yml from main repo, gateway with --bind loopback, cli sharing network namespace via network_mode: service:openclaw-gateway
• Config: gateway mode local, channels.telegram enabled (single bot), plugins enabled = telegram, google, anthropic, browser. No matrix configured. No OTEL endpoint.

Symptoms

docker logs openclaw-openclaw-gateway-1 after a recreate — final 3 lines:

[gateway] loading configuration…
[gateway] resolving authentication…
[gateway] starting...

No further output for the entire container lifetime. Healthcheck (fetch http://127.0.0.1:18789/healthz) fails because port 18789 is never opened.

docker exec <gateway> cat /proc/net/tcp shows only the Docker DNS resolver listening — port 18789 absent. cat /proc/<pid>/wchan for the Node process shows futex_wait_queue (event loop parked on an unresolved Promise).

force-recreate deterministically reproduces.

Diagnosis

Setting OPENCLAW_GATEWAY_STARTUP_TRACE=1 (env var; src/cli/gateway-cli/run.ts:145) gives:

startup trace: cli.server-import 1.0ms total=1.0ms
startup trace: cli.config-load 227.6ms total=256.4ms
startup trace: cli.config-snapshot 306.1ms total=576.6ms
[gateway] resolving authentication…
startup trace: cli.auth-resolve 0.3ms total=588.9ms
[gateway] starting...
startup trace: cli.gateway-loop 28.3ms total=617.2ms
startup trace: config.snapshot 622.1ms total=622.2ms
startup trace: config.auth 840.9ms total=1473.2ms
startup trace: control-ui.seed 0.1ms total=1477.6ms
<<< no further trace lines, ever >>>

Last successful step: control-ui.seed. Next-expected: plugins.bootstrap (server.impl.ts:599 calling prepareGatewayPluginBootstrap). That measure never returns, so the finally block in startupTrace.measure never emits its trace line.

prepareGatewayPluginBootstrap (server-startup-plugins.ts:35) awaits a Promise.all of two best-effort tasks:

1. runChannelPluginStartupMaintenance — only Matrix has runStartupMaintenance in the bundled dist, and Matrix is not configured here, so this should early-return.
2. runStartupSessionMigration — touches ~/.openclaw/agents/<id>/sessions/sessions.json (1 small file in this setup).

Neither has timeout protection, so any silent hang in either path stops the entire startup chain forever. --verbose flag does not help (it only changes stdout/stderr log level, not added log statements).

Workaround

Rebuild the local image from current main HEAD. After rebuild, healthy startup completes in ~1.6 seconds and reaches [gateway] ready. Trace shows the full chain through plugins.bootstrap → ... → sidecars.ready → ready. Multiple post-4.26 commits in this area look relevant (e.g. 5980040894 fix: avoid duplicate gateway config loads, da2a8bd6bb fix: scope runtime plugin preload to effective plugins, bd6035d977 fix: prefer built plugin artifacts at gateway startup, 81e1deade2 fix(release): restore plugin runtime loading). Haven't bisected to identify the exact culprit; happy to do so if helpful.