FIELD NOTES

Get your background jobs back on track.

Start with the command line. Understand the cause. Keep the fix.

• Homebrew says “started,” but the service is not running

  Inspect the launchd job and its configured logs; a registered service is not necessarily a healthy server.

• Why does my launchd job keep restarting?

  Inspect KeepAlive and the last exit code, then unload the job if you need it to stay stopped while debugging.

• Where are my launch agent’s logs?

  Check StandardOutPath and StandardErrorPath in the plist; use Console for processes that log through the unified logging system.

• launchctl load vs bootstrap: the old commands and their replacements

  load, unload, start and list guess the domain and report success even when nothing loaded. bootstrap, bootout, kickstart and print name it and fail loudly.

• launchctl bootstrap failed: 5 — what to check

  Check plist syntax, target domain, existing registration, file ownership, and the executable before retrying bootstrap.

• launchctl “Load failed: 5: Input/output error”: what it means and how to find the cause

  The job is already loaded, the plist does not parse, it has no Label, the file is writable by everyone, or the path is wrong. Five checks without sudo find which.

• How to stop a launch agent on a Mac

  Use launchctl kill for a temporary stop, or bootout to remove the job’s registration without deleting its plist.

• Find launch agents pointing to deleted apps

  Inspect Program and ProgramArguments for stale executable paths before removing an old launch agent.

• Why isn’t StartCalendarInterval running my script?

  Check the calendar dictionary, loaded state, executable permissions, and logs. launchd jobs do not inherit your interactive shell environment.

• LaunchAgent vs LaunchDaemon: which one should your job be?

  A LaunchAgent runs as a logged-in user and can show UI. A LaunchDaemon starts at boot as root, before anyone logs in, with no GUI. The folder decides which.

• “Background Items Added”: what the notification means and how to remove the item

  Find the plist or app behind the name with sfltool dumpbtm, then switch it off in Login Items or remove it with launchctl bootout.

• What is this launch agent? A lookup table for common Mac background items

  Look up a label from Login Items: which app it belongs to, what it does, whether to turn it off, and how to remove it properly.

• How to run a script at login on a Mac with a LaunchAgent

  Put a plist with RunAtLoad in ~/Library/LaunchAgents and load it with launchctl bootstrap. Login Items start apps; a LaunchAgent is how you run a script.

• What do the status numbers in launchctl list mean? (0, 78, 127, -9, -15)

  The second column is the last exit status: 0 is clean, a positive number is the program’s exit code, a negative one is the signal that ended it. 78 is EX_CONFIG.

• LaunchAgent says “command not found”: launchd’s PATH and how to fix it

  launchd starts jobs with PATH=/usr/bin:/bin:/usr/sbin:/sbin and none of your shell setup. Use absolute paths, or set PATH under EnvironmentVariables.

• LaunchAgent script gets “Operation not permitted”: launchd jobs and Full Disk Access

  Documents, Desktop and Downloads are privacy-protected, and Terminal’s permission does not carry over to the job. Move the files, or give the interpreter Full Disk Access.

• How to read launchctl print output: state, last exit code, runs and the rest

  Read state, pid, last exit code, runs, program and the three environment blocks first; most of the rest is memory and scheduling bookkeeping.

• launchctl “Boot-out failed: 5: Input/output error” (and 3, 1, 150): why bootout fails

  launchd has no job with that plist’s Label in that domain. Boot it out by service target instead; 3, 1 and 150 are the wrong label, missing sudo, and SIP.

• launchctl “Load failed: 119: Service is disabled”: how to enable a disabled launchd service

  The job has a persistent disable override in that domain, kept outside the plist. Find it with launchctl print-disabled, clear it with launchctl enable, then bootstrap again.

• Run a script when a file or folder changes on a Mac: launchd WatchPaths and QueueDirectories

  WatchPaths starts your script when a path changes; QueueDirectories runs it while a folder has files in it. A working plist, how to load it, and the gotchas.