← Back to PRs

#8642: fix: improve launchctl bootstrap error messages for GUI domain issues

by dbottme open 2026-02-04 07:29 View on GitHub →
gateway commands stale
## 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