macos-launchctl-port-conflict-resolution

name	macos-launchctl-port-conflict-resolution
description	Diagnose and resolve TCP port conflicts on macOS when launchctl-managed services compete for the same port. Covers process identification, plist editing, zombie-process killing, and clean restart. Trigger keywords: port conflict, EADDRINUSE, address already in use, launchctl service, port already in use, zombie process, lsof port.
license	MIT
metadata	{"version":"1.1.0","hermes":{"tags":["macOS","launchctl","Ports","Diagnostic","Services"],"related_skills":["postgresql-nix-macos-init"]}}

macOS launchctl port conflict resolution

Resolve "port already in use" / EADDRINUSE errors between launchctl-managed services on macOS.

Symptoms

• EADDRINUSE: address already in use :::3000
• Service fails to start; lsof shows multiple PIDs on the same port
• Service works intermittently; reconnects in loops with "stream errored out"
• After changing plist port, old process still listening on old port (zombie)

Workflow

Step 1 — diagnose

lsof -i :<PORT> -P                      # who's on this port
lsof -i TCP -P | grep LISTEN            # all listening ports
ps -fp <PID>                            # detail on a PID
launchctl list | grep <service-name>    # is it a launchctl service?

Look for: multiple PIDs claiming the same port, OR one PID still on the old port after a plist change.

Step 2 — locate the plist

find ~/Library/LaunchAgents -name "*<service-name>*" 2>/dev/null
find /Library/LaunchAgents -name "*<service-name>*" 2>/dev/null    # system-wide; may need sudo

User LaunchAgents are most common. System Integrity Protection blocks /System/Library/... plists even with sudo — use user agents instead.

Step 3 — edit the port

Common port specifications inside the plist:

• --port 3000 in ProgramArguments array
• PORT=3000 in EnvironmentVariables dict
• Hardcoded inside the executed script

Change <string>3000</string> → <string>9876</string> in whichever location applies. Watch for ports specified in MULTIPLE places — change all of them.

Step 4 — kill all instances (critical — prevents zombie loops)

Common mistake: only killing the new PID, leaving the old zombie fighting it for the port.

# Kill ALL processes for this service (both old and new)
kill -9 <OLD_PID> <NEW_PID> 2>/dev/null

# Or pattern-kill (safer when you don't know all PIDs)
pkill -9 -f "<service-pattern>"

launchctl stop alone does NOT kill orphaned processes — kill -9 on all matching PIDs is required.

Step 5 — restart cleanly

# Modern forms (unload/load are deprecated aliases that still work):
launchctl bootout   gui/$(id -u) ~/Library/LaunchAgents/<service>.plist
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/<service>.plist
# Legacy equivalent:
launchctl unload ~/Library/LaunchAgents/<service>.plist
launchctl load   ~/Library/LaunchAgents/<service>.plist

A full unload/bootout + load/bootstrap cycle is required to pick up plist changes — stop+start (and kickstart -k) won't re-read the plist.

Step 6 — verify

lsof -i :<NEW_PORT> -P                  # exactly ONE PID on new port
launchctl list | grep <service-name>    # service shows running with PID
curl -s http://localhost:<NEW_PORT>/health 2>/dev/null  # if health endpoint exists

Verification checklist:

• Conflicting processes identified with lsof
• Plist file located
• Port changed in plist (all locations if multiple)
• All zombies killed (-9, not just stop)
• Service unloaded and reloaded (not just restarted)
• New port confirmed; old port available

Common scenarios

Example: a background bridge service vs a web app

# Symptom: Rails can't start on :3000
lsof -i :3000                                    # shows node bridge.js + ruby

# Find and edit plist
ls ~/Library/LaunchAgents/com.example.bridge-service.plist
sed -i 's/3000/9876/g' ~/Library/LaunchAgents/com.example.bridge-service.plist
# ^ GNU form (nix machines shadow BSD sed; bare `sed -i ''` FAILS there — verified 2026-06-12).
#   Stock macOS without nix: /usr/bin/sed -i '' 's/3000/9876/g' <plist>

# Kill zombies
pkill -9 -f "bridge-service"

# Reload
launchctl unload ~/Library/LaunchAgents/com.example.bridge-service.plist
launchctl load   ~/Library/LaunchAgents/com.example.bridge-service.plist

# Verify
curl http://localhost:9876/health   # {"status":"connected"}

Multiple PostgreSQL instances

lsof -i :5432
# If another postgres is running:
psql -U $(whoami) -d postgres                 # use it
# OR kill it (only if safe):
kill -9 $(lsof -ti:5432)
# OR change port in postgresql.conf

Dev server on a standard port (Vite, Next.js, Rails, etc.)

Three options, in order of preference:

1. Change the dev server port (CLI arg or env var).
2. Stop the conflicting launchctl service temporarily.
3. Reconfigure the launchctl service permanently (this skill).

Pitfalls

• launchctl stop is not enough — must unload then load to pick up plist changes.
• KeepAlive=true services auto-restart — without changing the plist, the old port keeps getting reclaimed.
• Ports specified in multiple places — some services have it in both ProgramArguments AND EnvironmentVariables; change both.
• Zombie processes after plist edit — lsof showing - (no process) for old port when edit was incomplete; use pkill -9 -f for pattern cleanup.
• System Integrity Protection — /System/Library/... plists can't be modified even with sudo; recreate as a user agent in ~/Library/LaunchAgents/.

Management commands

launchctl list                                              # all loaded services
launchctl list | grep -v "^-"                               # only user services
launchctl start com.example.service                          # start
launchctl stop com.example.service                           # stop
launchctl unload ~/Library/LaunchAgents/com.example.service.plist
launchctl load   ~/Library/LaunchAgents/com.example.service.plist
launchctl kickstart -k gui/$(id -u)/com.example.service      # restart-safe (works whether loaded or not)
tail -f ~/Library/Logs/com.example.service.log               # logs (if configured)