#8642: fix: improve launchctl bootstrap error messages for GUI domain issues
gateway
commands
stale
Cluster:
Cross-Platform Fixes
## Summary
- Improve error message when launchctl bootstrap fails with "Could not find domain" error
- Add guidance for common causes and workarounds
- Add `isGuiDomainError` flag to `repairLaunchAgentBootstrap` result
## Problem
When running `openclaw gateway install` or the install script via SSH or in non-standard environments, users get the cryptic error:
```
launchctl bootstrap failed: Could not find domain for user gui: 1000
```
This error provides no guidance on what went wrong or how to fix it.
## Solution
Detect the "Could not find domain" error and provide a helpful error message:
```
launchctl bootstrap failed: Could not find domain for user gui: 1000
This error typically occurs when:
• Running via SSH without a GUI session
• Running in a container or non-standard environment
• The user account lacks a launchd GUI domain
Try running this command from a local terminal with a GUI session,
or use 'openclaw gateway start' to run the gateway directly.
```
## Test plan
- [x] All 14 launchd tests pass
- [x] Build and check pass
- [x] Error handling added in both `installLaunchAgent` and `repairLaunchAgentBootstrap`
Fixes #8619
---
🤖 Generated with Claude Code
**AI Disclosure**: This PR was generated with AI assistance (Claude Opus 4.5).
- Testing level: Verified existing tests continue to pass
- Code understanding: Analyzed launchctl error paths and added user-friendly error messages
<!-- greptile_comment -->
<h2>Greptile Overview</h2>
<h3>Greptile Summary</h3>
This change improves macOS launchd diagnostics by detecting the common `launchctl bootstrap` failure that contains "Could not find domain" and, in `installLaunchAgent`, throwing a more actionable error message with likely causes (SSH/no GUI session, container/non-standard env) and an alternative command (`openclaw gateway start`).
It also extends `repairLaunchAgentBootstrap` to return an `isGuiDomainError` flag alongside the existing `ok`/`detail` result, enabling callers (e.g., doctor flows) to tailor messaging without needing to parse stderr themselves. The changes are localized to `src/daemon/launchd.ts` but impact user-facing diagnostics in gateway install/repair paths.
<h3>Confidence Score: 4/5</h3>
- This PR is generally safe to merge and mainly adjusts user-facing error messaging.
- Changes are localized and low risk (string parsing + message formatting). The main remaining concern is functional completeness: the new `isGuiDomainError` signal isn’t currently used by at least one key caller (`doctor-gateway-daemon-flow`), so users may still see the old cryptic messaging in that path.
- src/daemon/launchd.ts; src/commands/doctor-gateway-daemon-flow.ts
<!-- greptile_other_comments_section -->
<!-- /greptile_comment -->
Most Similar PRs
#10182: fix: skip non-openclaw LaunchAgents in doctor gateway scan
by Yida-Dev · 2026-02-06
78.5%
#15903: fix(doctor): stricter gateway service detection to prevent false po...
by Shuai-DaiDai · 2026-02-14
76.8%
#8260: fix(macOS): gateway readiness detection + reversible Configure later
by xksteven · 2026-02-03
76.6%
#15619: fix: clean up orphan LaunchAgent plist on bootstrap failure
by superlowburn · 2026-02-13
76.2%
#9173: Fix: Improve error messaging for API rate limits and billing errors
by vishaltandale00 · 2026-02-04
76.2%
#2530: fix(gateway): improve auth error for native apps
by Episkey-G · 2026-01-27
75.7%
#16845: fix(daemon): gateway auto-restart on SIGTERM + agent restart guidel...
by kiminbean · 2026-02-15
75.4%
#4653: fix(gateway): improve crash resilience for mDNS and network errors
by AyedAlmudarra · 2026-01-30
75.1%
#4709: fix(daemon): include user bin dirs in macOS LaunchAgent PATH
by ekson73 · 2026-01-30
75.0%
#20390: fix(daemon): fall back to /tmp for launchd logs on removable volumes
by lemoz · 2026-02-18
74.8%