--- summary: "Symptoms and fixes for profile advertisement, authorization, bootstrap, enrollment, and teardown" title: "Cloud worker troubleshooting" read_when: "A cloud dispatch, move, stop, or publication failed and you need the matching fix." --- Symptoms you may see when dispatching to or running on a cloud worker, and the check that resolves each one. ## Troubleshooting - **No cloud profile is advertised** — run the `operator.read`-scoped `openclaw gateway call environments.list --params '{}'`. If the response has no `profiles`, ask an administrator to validate `cloudWorkers.profiles`, inspect the provider plugin, and restart the Gateway. This is a configuration or provider-activation problem, not an authorization result. - **Cloud destinations are hidden or an RPC is denied** — cloud profile dispatch and profile-target moves require `operator.admin`. `operator.write` can dispatch or move to an eligible paired device, move to the Gateway, and reclaim a placement; `operator.read` alone can discover profiles but cannot start, stop, or move a session. Profile configuration, infrastructure pairing, Connect machine, raw environment lifecycle, direct `execNode` execution, incognito sessions, and arbitrary host or node paths remain `operator.admin`. - **The selected runtime lacks cloud placement support** — choose a model whose advertised runtime supports cloud placement. The bundled OpenClaw and Codex runtimes are supported; undeclared runtimes remain local-only. - **Codex cannot use a cloud profile** — verify that the profile advertises `remote-exec`, the Gateway enables a trusted Codex plugin installation, and `gateway.nodes.commands.allow` includes `codex.exec-server.stdio.v1` without a matching deny rule. Bootstrap supplies the cloud-node plugin automatically. Approve the exact node invocation when prompted. Codex does not require an available OpenClaw worker slot; a missing plugin or denied command must be corrected rather than bypassed with Gateway or SSH execution. - **The portal tool is unavailable on a worker** — confirm the session uses OpenClaw `worker-turn` on an enrolled node that advertises portal-stream support. Update older node bundles when necessary. SSH-backed `remote-exec` placements, including Codex sessions, do not run the OpenClaw worker tool loop; move the session back to the Gateway with `sessions.move` when a Gateway-hosted portal is needed. - **"Worker bootstrap requires Node.js on the leased host"** — add a Node install to `settings.setup` (see [The setup command](/gateway/cloud-workers/setup-and-bundle-installation#the-setup-command)). - **`gh: command not found` on a cloud worker** — install GitHub CLI in `settings.setup` (see the Debian/Ubuntu example in [Configuration](/gateway/cloud-workers#configuration)), or install it on the paired worker host. Crabbox developer images include it; the sealed worker bundle does not. - **AWS instance-role attestation fails** — clear `aws.instanceProfile` (and `CRABBOX_AWS_INSTANCE_PROFILE`, if set). Install Crabbox 0.41.1 or newer; older binaries do not satisfy the fixed-ID and authoritative `providerMetadata.instanceProfileAttached` contracts required for AWS admission. - **Dispatch or workspace recovery fails** — inspect `environments.list` and `sessions.describe`. A failed environment exposes its bounded environment error. A failed placement exposes `recoveryError` plus its durable per-session `terminalReason`; the selected Control UI chat shows that terminal reason above the composer. When deeper diagnosis is necessary, an operator on the Gateway host can inspect the durable worker state read-only. Do not edit the state database to bypass lifecycle fencing. - **Crabbox setup cannot reach the lease** — check the selected backend's networking and setup-transport requirements in the [Crabbox provider reference](https://crabbox.sh/providers/index.html). Correct Crabbox's configuration and rerun `crabbox doctor --provider --json` before retrying. - **Session shows a reclaimed or suspended badge after being idle** — this is expected when its profile sets `suspendAfter`. The next message provisions a replacement worker, warm when an image exists. - **A warm image is unavailable** — a new allocation can select cold provisioning before its choice is recorded. An already admitted allocation keeps its original cold/checkpoint choice through retries. If its checkpoint cannot be forked, resolve the provider error or stop that allocation before starting a replacement; retry does not switch images silently. - **Warm-image migration or capacity blocks dispatch** — run `openclaw doctor --fix` for legacy state and follow its exact cleanup guidance. For capacity, stop outstanding workers or resolve pending image cleanup with `openclaw crabbox warm-images`; allocation choices and cleanup obligations are never evicted to make room. - **Cloud bootstrap requests a rebuild** — run `pnpm build` in the Gateway source checkout, then restart the Gateway and retry. The running build, its package metadata, and the built plugin outputs must agree; editing source or matching the displayed version alone is insufficient. - **Cloud bootstrap download fails** — the error identifies the connection, TLS, HTTP-response, or body-transfer phase. A `download TLS` reset happened before an HTTP response; check the worker provider's outbound policy and the Gateway's TLS endpoint from the worker, not only from the Gateway host. For an HTTP status, check proxy routing and download authorization. A `download body` error means response headers arrived; inspect the interrupted transfer, local disk, or archive-integrity error. Use a Gateway origin permitted by the provider's policy; do not disable certificate validation or bypass that policy. - **Node enrollment times out** — inspect the bootstrap download or install error, node process state, and bounded node-log tail included in the enrollment error. Verify that profile setup installed a supported Node.js release and npm, that npm can reach the dependency registry, and that the box can reach the Gateway's advertised TLS URL. Forward `/__openclaw__/worker-bootstrap/artifacts/` as well as the public worker/node WebSocket routes through your proxy. If the error contains `proxy_attribution_required`, add the reverse proxy's source address to `gateway.trustedProxies`. - **Client timeout while dispatching** — `openclaw gateway call` defaults to a 10s timeout; pass `--timeout` generously. Dispatch keeps running server-side either way, and an identical retry on the same Gateway joins that in-flight operation instead of provisioning another worker. A retry with a different profile or session identity is rejected. - **Provider authorization fails after `doctor` passes** — read-only readiness does not prove permission to allocate or tear down a lease. Inspect the denied action and follow the selected provider's provisioning and cleanup requirements in the [Crabbox provider reference](https://crabbox.sh/providers/index.html). - **Worker reclaimed after a Gateway update** — OpenClaw releases idle cloud workers built for the previous build, keeps the session and workspace, and provisions a replacement on the next message. Workers interrupted mid-turn or while starting, or holding unaccepted results, still fail and need explicit redispatch. - **Cloud workspace conflict notice** — the turn completed and kept the local version of each listed path. Use the staged-ref commands in the notice to inspect or take the cloud version; no retry is required for the non-conflicting changes, which are already applied. - **Cloud session disk-space warning** — delete unneeded files from the remote workspace or stop the cloud worker before large writes. The warning clears automatically after the next successful sample shows enough free space; a failed sample leaves the last successful warning visible and does not affect the session lifecycle. - **“The previous cloud turn's workspace result is still reconciling”** — the Gateway waited briefly for the prior result's durable fence and could not acquire the session claim. Wait for reconciliation to finish, then retry the turn; restarting the Gateway is safe because recovery preserves staged results before reclaiming a dead worker. - **GitHub publication failed** — for Gateway-brokered publication through **Publish PR** or remote-exec `github_publish`, open **Agents → Tools → GitHub Identity** and confirm the effective `@login`, selected scope, access expiry, and refresh state. Reconnect GitHub when refresh is expired or unavailable; use a managed PAT only as the explicit fallback. For push rejection, inspect repository write access and branch drift; `/user` verification does not prove repository write access and the broker never force-pushes. For pull request rejection, grant pull-request write access and retry **Publish PR** or call `github_publish` again with a new tool call. - **Repository publication is unavailable** — Git clean filters, unsafe Git configuration, or failed publication-snapshot validation can prevent preparing a publishable checkpoint. Raw recovery checkpoints and normal Stop still preserve accepted changes. Correct the repository configuration, then run another turn or save an edit to prepare a new checkpoint before requesting publication again. - **Lease housekeeping** — `crabbox list --provider --json` is a read-only inventory. `crabbox stop --provider --id ` and `crabbox release --provider --id ` are destructive and release a lease manually. OpenClaw keeps the lease alive while its session is placed, then stops heartbeating during teardown so genuinely idle leases expire on the profile's `idleTimeout`. A temporary heartbeat failure, including a lease claim conflict, warns and keeps the next scheduled renewal. Crabbox 0.43.0 and older do not expose the heartbeat command; OpenClaw warns once per environment and cannot prevent coordinator-idle reaping on those binaries.