Troubleshooting

Common issues, error messages, launchd gotchas, and diagnostic commands.

Common Issues

Agent not loading

Symptoms: Job shows as "Unloaded" in the dashboard after saving. launchctl list does not show the job label.

Possible causes:

1. Plist file permissions are wrong. launchd silently ignores plist files with incorrect permissions. The file must be owned by the current user and have permissions 644 or stricter.

   # Check permissions
   ls -la ~/Library/LaunchAgents/com.launchpad.myjob.plist
   
   # Fix if needed
   chmod 644 ~/Library/LaunchAgents/com.launchpad.myjob.plist

2. Malformed plist XML. Validate the plist with plutil:

   plutil -lint ~/Library/LaunchAgents/com.launchpad.myjob.plist

3. Duplicate label. Another agent with the same label is already registered. Check with launchctl list | grep myjob.

Permission denied errors

Symptoms: Job loads but exits immediately with exit code 78 or 1. Stderr shows "Permission denied".

Solution: Ensure the executable has execute permissions:

chmod +x /path/to/your/script.sh

Also check that the script's shebang line is correct (e.g., #!/bin/bash or #!/usr/bin/env python3).

Schedule not firing

Symptoms: Job is loaded and enabled but never runs at the expected time.

Possible causes:

• Mac was asleep. StartCalendarInterval does not fire while the machine is asleep. If the Mac was sleeping at the scheduled time, the job runs once when the Mac wakes up (launchd coalesces missed runs).
• Using StartInterval and StartCalendarInterval together. This has undefined behavior. Use only one. LaunchPad prevents this at the form level, but manually-edited plists may have this issue.
• Incorrect Weekday values. In launchd, Sunday is 0 and Saturday is 6. This is different from cron on some systems where Sunday can be 7.
• ThrottleInterval throttling. launchd enforces a minimum 10-second interval between job launches. If your schedule would trigger more frequently, launchd silently throttles it.

Log file missing

Symptoms: Job runs but log viewer shows "No output captured".

Possible causes:

• No StandardOutPath/StandardErrorPath in the plist. LaunchPad auto-defaults these for managed jobs, but external jobs may not have them set. Without these keys, stdout/stderr goes to /dev/null.
• Log directory doesn't exist. LaunchPad creates ~/Library/Logs/LaunchPad/ automatically, but if the directory was deleted, log writes will fail silently.
• Disk full. If the disk is full, log files cannot be written. Check available space with df -h.

Dashboard port conflict

Symptoms: LaunchPad fails to start with "EADDRINUSE" error.

Solution: Another process is using port 24680. Find it:

# Find the process using port 24680
lsof -i :24680

# Or change the port via environment variable
LAUNCHPAD_PORT=24681 pnpm start

launchd Gotchas

launchd has been stable for 15+ years, but it has quirks that trip up even experienced macOS users.

Domain targets (modern vs. legacy syntax)

Apple has deprecated the load/unload subcommands in favor of the domain-target syntax. Both still work, but you may see deprecation warnings.

# Legacy (still works, prints deprecation warning)
launchctl load ~/Library/LaunchAgents/com.launchpad.myjob.plist
launchctl unload ~/Library/LaunchAgents/com.launchpad.myjob.plist

# Modern (recommended)
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.launchpad.myjob.plist
launchctl bootout gui/$(id -u)/com.launchpad.myjob

# Check if a job is loaded (modern)
launchctl print gui/$(id -u)/com.launchpad.myjob

Unload before reload

When editing a plist, you must unload (bootout) the job before loading (bootstrapping) the updated version. Loading a new plist without unloading the old one causes undefined behavior -- sometimes the old version keeps running, sometimes launchd returns a "service already loaded" error.

LaunchPad handles this automatically during job edits.

ProgramArguments vs. Program

The ProgramArguments key takes an array where the first element is the executable and subsequent elements are arguments. The Program key takes a single string (the executable path) with no arguments. If you use Program, you cannot pass arguments.

StartCalendarInterval array wrapping

A single StartCalendarInterval dict works fine for one schedule. But if you want multiple schedules (e.g., weekdays at 9 AM), each day needs its own dict in an array. Forgetting the array wrapper causes only the first schedule to fire.

Environment differences from Terminal

LaunchAgents run with a minimal environment -- not your shell profile (.zshrc, .bashrc). This means:

• PATH is minimal (/usr/bin:/bin:/usr/sbin:/sbin)
• Homebrew paths (/opt/homebrew/bin) are not included
• Custom environment variables from your shell are not available

Fix: Use absolute paths for executables (e.g., /opt/homebrew/bin/python3 instead of python3) or set EnvironmentVariables in the plist with a custom PATH.

Diagnostic Commands

Useful terminal commands for debugging LaunchAgent issues.

# List all loaded user LaunchAgents
launchctl list

# Get detailed info about a specific job
launchctl print gui/$(id -u)/com.launchpad.myjob

# Check if a plist is valid XML
plutil -lint ~/Library/LaunchAgents/com.launchpad.myjob.plist

# Convert plist to readable JSON for inspection
plutil -convert json -o - ~/Library/LaunchAgents/com.launchpad.myjob.plist | python3 -m json.tool

# List all plist files in user LaunchAgents directory
ls -la ~/Library/LaunchAgents/

# Check system log for launchd errors
log show --predicate 'subsystem == "com.apple.xpc.launchd"' --last 5m

# Check what port LaunchPad is running on
lsof -i :24680

# View LaunchPad server logs
tail -f ~/Library/Logs/LaunchPad/server.log

# Check SQLite database integrity
sqlite3 ~/.launchpad/launchpad.db "PRAGMA integrity_check;"

# Count total jobs in database
sqlite3 ~/.launchpad/launchpad.db "SELECT COUNT(*) FROM jobs WHERE archived_at IS NULL;"

Error Messages

Frequently Asked Questions