#22262: fix(gateway): add pairing-repair command hint on 1008 connect failures
channel: discord
gateway
size: L
## Summary
When gateway connect fails with `pairing required` (typically 1008 during scope-upgrade), the client currently logs a generic connect failure.
This change adds an explicit remediation hint in the connect error text:
- `openclaw devices approve --latest`
- fallback: `openclaw devices list` to choose a request id
## Why
In real incidents, restarting the gateway does not resolve pending repair requests. The fastest fix is device approval. This message now points users to the correct recovery path.
## Testing
- Ran: `pnpm vitest run src/gateway/client.test.ts`
- Result: 2 tests passed
## AI Assist
AI-assisted (Codex), reviewed before commit.
<!-- greptile_comment -->
<h3>Greptile Summary</h3>
Adds helpful pairing-repair command hint when gateway connection fails with "pairing required" errors (typically 1008 during scope-upgrade). The new `formatGatewayConnectError` function detects pairing errors and appends actionable remediation steps pointing users to `openclaw devices approve --latest` or `openclaw devices list`.
<h3>Confidence Score: 5/5</h3>
- This PR is safe to merge with minimal risk
- Simple, focused change that adds helpful user-facing error messaging without altering control flow or core logic. The new function is defensive (lowercases input, handles unknown types), has clear purpose, and is covered by existing tests (2 tests passed as noted in PR description)
- No files require special attention
<sub>Last reviewed commit: 3a18d90</sub>
<!-- greptile_other_comments_section -->
<sub>(3/5) Reply to the agent's comments like "Can you suggest a fix for this @greptileai?" or ask follow-up questions!</sub>
<!-- /greptile_comment -->
Most Similar PRs
#21148: fix(gateway): add request-aware pairing recovery hints and docs
by cluster2600 · 2026-02-19
89.7%
#22066: fix(cli): add actionable hints for gateway close errors
by pierreeurope · 2026-02-20
84.6%
#22712: fix(gateway): auto-approve all device pairing for localhost connect...
by NewdlDewdl · 2026-02-21
83.3%
#6846: fix: bridge node.pair.* tools to device pairing store
by cortexuvula · 2026-02-02
82.6%
#19088: fix(gateway): allow startup with unset mode and fix pairing for local…
by mdanassaif · 2026-02-17
81.4%
#22280: fix(gateway): silently auto-approve local paired-device scope upgrades
by abhishekp76 · 2026-02-21
81.3%
#17425: fix(gateway): auto-approve scope/role upgrades for already-paired d...
by sauerdaniel · 2026-02-15
81.1%
#23503: fix: preserve pairing state on device token mismatch + migrate lega...
by dorukardahan · 2026-02-22
81.0%
#21651: fix(gateway): token fallback + operator.admin scope superset in pai...
by lan17 · 2026-02-20
80.8%
#16310: fix(ws-connection): skip device pairing when client authenticates w...
by nawinsharma · 2026-02-14
80.6%