Skip to content

fix(gateway): self-heal missing launchd plist on start#3334

Closed
Bartok9 wants to merge 1 commit into
NousResearch:mainfrom
Bartok9:fix/launchd-missing-plist-recovery
Closed

fix(gateway): self-heal missing launchd plist on start#3334
Bartok9 wants to merge 1 commit into
NousResearch:mainfrom
Bartok9:fix/launchd-missing-plist-recovery

Conversation

@Bartok9

@Bartok9 Bartok9 commented Mar 27, 2026

Copy link
Copy Markdown
Contributor

Summary

When the launchd plist file is missing (manual cleanup, failed upgrade, launchd state drift), hermes gateway start now regenerates the plist, loads it, and starts the service instead of crashing with exit status 3.

Problem

Previously, refresh_launchd_plist_if_needed() returned early if the plist was missing:

if not plist_path.exists() or launchd_plist_is_current():
    return False

And the recovery path in launchd_start() was skipped because it only triggered when the plist existed:

if e.returncode != 3 or not plist_path.exists():
    raise

This meant users in the missing-plist state had to run hermes gateway install manually to recover.

Solution

Check for missing plist at the start of launchd_start() and self-heal:

  1. Regenerate the plist
  2. Load it with launchctl load
  3. Start the service

This makes hermes gateway start robust to missing plists, regardless of how the plist disappeared.

Testing

Added regression test: test_launchd_start_recreates_missing_plist_and_loads_service

Fixes #3318

When the launchd plist file is missing (manual cleanup, failed upgrade,
launchd state drift), `hermes gateway start` now regenerates the plist,
loads it, and starts the service instead of crashing with exit status 3.

Previously, `refresh_launchd_plist_if_needed()` returned early if the
plist was missing, and the recovery path in `launchd_start()` was skipped
because it only triggered when the plist existed.

Changes:
- Check for missing plist at the start of `launchd_start()`
- Regenerate and load the service definition if missing
- Simplify the exception handler (plist existence check no longer needed)

Fixes NousResearch#3318
@teknium1

Copy link
Copy Markdown
Contributor

Merged via #3601 — cherry-picked onto current main with authorship preserved, test added. Thanks @Bartok9!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

macOS: hermes gateway start fails when launchd plist is missing; should recreate/load service

2 participants