hermes - 💡(How to fix) Fix [Bug]: macOS 26.4.1: hermes gateway start fails — launchctl kickstart gui/502 returns error 125 (Domain does not support specified action) [1 participants]

Bug Description

On macOS 26.4.1 (Darwin 25, Build 25E253, Darwin Bootstrapper 7.0.0), hermes gateway start and hermes gateway install fail with error 125 because the gui/<uid> launchd domain no longer supports kickstart or bootstrap operations.

$ hermes gateway start
Could not kickstart service "ai.hermes.gateway": 125: Domain does not support specified action
X   Start failed: Command '['launchctl', 'kickstart', 'gui/502/ai.hermes.gateway']' returned non-zero exit status 125.

Environment

• macOS 26.4.1 (Build 25E253)
• Darwin Bootstrapper 7.0.0 (RELEASE_ARM64E)
• Hermes v0.13.0 (2026.5.7)
• Apple Silicon (M1)

Root Cause

hermes_cli/gateway.py line 2739 hardcodes the launchd domain as gui/<uid>:

def _launchd_domain() -> str:
    return f"gui/{os.getuid()}"

On macOS 26.4.1, this domain does not support any management operations:

The user/<uid> domain partially works (print, enable succeed) but bootstrap and kickstart into it also fail with error 5.

Affected Code Paths

All call sites using _launchd_domain() in hermes_cli/gateway.py:

• Line 2879: launchd_install() -- bootstrap with check=True -> error 5
• Line 2910: launchd_start() -- kickstart with check=True -> error 125
• Line 2916: launchd_start() -- kickstart with check=True -> error 125
• Line 2922: launchd_start() fallback -- kickstart with check=True -> error 125
• Line 2856-2857: refresh_launchd_plist_if_needed() -- bootout/bootstrap with check=False (silent failures)
• Line 2927: launchd_stop() -- target resolution

The error-handling at line 2918 only checks for return codes 3 and 113, missing error 125 entirely.

Workaround

Running the gateway directly via nohup works correctly:

nohup python -m hermes_cli.main gateway run --replace > ~/.hermes/logs/gateway.log 2>&1 &

This bypasses launchd entirely.

Related Issues

• #11323: Similar issue -- launchctl bootstrap gui/501 returns exit status 5 on macOS. The proposed fix (fallback to launchctl load -w) also fails on macOS 26.4.1 because launchctl load crashes with exit 134.
• #11932: macOS launchd restart logic broken -- launchd_restart() returns early after SIGUSR1

Proposed Fix

Option A: Switch to user/<uid> domain with error handling

Change _launchd_domain() to try user/<uid> when gui/<uid> fails, with graceful degradation.

Option B: Catch error 125 and 5, provide clear guidance

Add return codes 5 and 125 to the handled set in all CalledProcessError handlers. When these occur, print a clear message suggesting the nohup workaround instead of a cryptic traceback.

Option C: Auto-detect unsupported domain

At startup, test if gui/<uid> or user/<uid> supports kickstart and fall back to nohup-based launch if not. This would make hermes gateway start work transparently across all macOS versions.

Why priority:high

This breaks hermes gateway start/stop/restart on all macOS 26.x systems. macOS 26 is the current public release as of May 2026. Every Hermes user on macOS 26 who tries to use the gateway service commands will hit this error.