launchd StartCalendarInterval Missed: 4 Causes I Measured

This Mac mini publishes on a ten-slot unattended schedule, and in the two days since it last booted, launchctl print gui/501/com.mmm.daily-content reports runs = 21. Counting the slots that have come around since kern.boottime (Mon Aug 10 18:38:31 2026) gives 2 on the 10th, 10 on the 11th, and 9 today. Twenty-one. Not a single firing lost.

That is a useless number for writing about missed runs, and the reason is in the power log: pmset -g log | grep -c "Entering Sleep" returns 0. The machine has never slept, so it has never had the chance to miss anything. To find out what actually drops a StartCalendarInterval firing, I had to manufacture the failures. Six throwaway LaunchAgents, bootstrapped into gui/501 at 10:31:51Z and torn down 8 minutes later, produced four distinct causes. One of them is sitting in a plist Apple ships.

The schedule does not live where the man page says it does

man 5 launchd.plist (dated 30 July 2019 on macOS 26.4.1) says "launchd will start the job the next time the computer wakes up." But dump a calendar job with launchctl print and launchd is not the thing holding the clock:

	event triggers = {
		com.picklog.lab.past1.268435520 => {
			service = com.picklog.lab.past1
			stream = com.apple.launchd.calendarinterval
			monitor = com.apple.UserEventAgent-Aqua
			descriptor = {
				"Minute" => 0
				"Hour" => 3
			}
		}
	}

The schedule is an event stream watched by /usr/libexec/UserEventAgent (Aqua), pid 599 here. And grep the entire launchctl print output of a live calendar job for the word "fire": 0 matches. There is no next-fire-date field anywhere. And log show --last 3h --predicate 'process == "launchd"' returns nothing for these labels either, so there is no spawn record after the fact. When someone says a job was missed, there is no artefact in the system that either confirms or denies it — the same blind spot that let a launchd job fail silently here for 20 hours.

Cause 1: the time had already passed when you loaded the plist

The coalescing sentence gets quoted a lot, and it reads like a general catch-up promise. I loaded two agents at 19:31 local time: one with a single {Hour: 3, Minute: 0}, the other with an array of six dictionaries, 03:00 through 08:00, every one of them hours in the past.

Both reported runs = 0 and stayed there. No immediate run, no single coalesced run for the six. Coalescing applies to intervals that transpire while the machine is asleep, and being freshly bootstrapped is not that. It is the one behaviour that genuinely separates launchd from cron, and it is narrower than the sentence sounds. If a plist gets reinstalled by a config-management run at 09:00, its 03:00 job does not happen that day.

Cause 2: the job was still running — and this one is undocumented

The man page says plainly, under StartInterval, that "if the job is running during an interval firing, that interval firing will likewise be missed." That sentence does not appear under StartCalendarInterval. So I gave one agent an empty <dict/> (every field wildcard, so every minute) and a body of sleep 150:

10:32:05 START pid=5036
10:34:35 END   pid=5036      # firings at 10:33 and 10:34 arrived here
10:35:00 START pid=12887
10:37:30 END   pid=12887     # firings at 10:36 and 10:37 arrived here
10:38:04 START pid=15674

Three runs where the schedule called for seven. Calendar firings that arrive during an execution are dropped, with no queue and no catch-up. The behaviour matches the StartInterval paragraph exactly, but you will not find it written down for the calendar key.

The interesting half is what happens on restart. Each new run begins on a wall-clock minute boundary — 10:35:00, 10:38:04 — not 150 seconds after the previous one. A 90-minute publishing slot that overruns loses the next slot entirely, but the slot after that still lands on the hour.

The same test with StartInterval fails the other way

An identical sleep 150 job under StartInterval 60:

10:31:51 bootstrap
10:32:51 START   # +60s from load, not at load
10:35:21 END
10:36:21 START   # +60s from END
10:38:52 END
10:39:52 START   # +60s from END

The timer restarts from process exit, so the effective period is 150 + 60 = 210 seconds. Nothing is lost, and nothing stays on schedule. Over a day that job walks steadily away from the clock.

Cause 3: launchd threw your key away without telling you

Today is a Wednesday. I loaded two agents with identical times, both asking for weekday 1 (Monday). The only difference was the capital D:

Key spelling	Result at 19:36
Weekday (documented)	did not fire, runs = 0
WeekDay	fired, runs = 1

An unrecognised key is silently discarded, which deletes the constraint rather than failing the job. A weekly job becomes a daily one. Nothing catches it: plutil -lint returns OK, launchctl bootstrap exits 0, and the launchctl print descriptor echoes "WeekDay" => 1 back at you as though it meant something.

So I swept every launchd plist on the machine — 888 files across the two system directories and the two /Library ones — for calendar dictionaries using anything outside the five documented keys (Minute, Hour, Day, Weekday, Month). Fourteen plists use StartCalendarInterval at all. Exactly two use an undocumented key, and both belong to Apple:

/System/Library/LaunchDaemons/com.apple.gkreport.plist
  {Hour: 3, Minute: 52, WeekDay: 5}
/System/Library/LaunchDaemons/com.apple.usbctelemetryd.plist
  {Hour: 12, Minute: 0, Second: 0}

By the rule I measured, the Gatekeeper report daemon asks for Thursdays and gets every day at 03:52. I have not audited when gkreport actually runs — it is a system daemon under SIP, so this is inference from the file plus the experiment, not an observation of that job.

Second is not in the man page either, so I tested it: an agent set to {Hour: 19, Minute: 38, Second: 40} fired at 19:38:04. Discarded, same as the typo. One rule covers both: the calendar dictionary accepts any key you put in it and drops whatever it does not recognise.

Cause 4: sleep, which I could not test

This is the cause everyone actually hits, and it is the one I have no measurement for. The mini runs an unattended publishing pipeline, so I cannot put it to sleep to watch what happens. Everything below is quotation, not data.

Apple's Scheduling Timed Jobs guide, last updated in 2016, draws the line at sleep versus off: a calendar job runs on wake, but "if the machine is off when the job should have run, the job does not execute until the next designated time occurs." Everything else is simply skipped.

A February 2026 developer forums thread is more current and more unsettling. The original poster reported jobs starting while the machine slept and then suspending mid-execution, resuming hours later, and initially blamed a version change. They then corrected themselves: macOS 26, 15, and 12 all behave this way, and the variable is the lid. Open lid gives DarkWake behaviour; closed lid matches the documentation. Desktop Macs with no lid were left undetermined, which covers this machine. An Apple DTS engineer replied in the same thread: "From an API perspective, launchd doesn't guarantee anything about the power state of the system when it starts your job based on StartCalendarInterval."

The complaints are old. An Apple discussions thread from 2013 has users measuring firings 1 to 19 minutes late while cron on the same machine stayed punctual, one of them noting that moving the mouse over a remote desktop session made the timing accurate again. It closed unresolved.

What Apple uses when it actually needs periodic work

Fourteen plists in /System/Library use StartCalendarInterval. In the same 886 files, 121 use com.apple.xpc.activity, nested under LaunchEvents, declaring 295 activities between them. I missed this on the first pass because I only looked at top-level keys, and nearly wrote it off as a bad grep.

The keys those activities use are the tell. Across 295 definitions: Priority 275 times, Repeating 248, Interval 211, AllowBattery 210, GracePeriod 101, PowerNap 82, Delay 61. Gamecontrollerd's asset check reads {"Interval": 432000, "GracePeriod": 172800, "Priority": "Maintenance", "Repeating": true}, which means every five days, and it may slip by up to two.

That grace window is the thing StartCalendarInterval has no concept of. A calendar firing is an instant, and an instant that passes is gone. The word "missed" describes a scheduler that has no tolerance to spend, which is why the fix is never a plist tweak.

What this changed here

Of the 25 LaunchAgents installed on this machine, 15 use a calendar schedule, spread over 50 firing points. Nine of those 15 also set RunAtLoad, the standard community hedge: if a reboot eats the day's firing, the job at least runs when the agent loads. Three that do not are mine. Adding RunAtLoad to the ten-slot publisher would make every reboot trigger a publish, which is worse than losing a slot, so that one stays as it is; daily-report and daily-revenue are a different question and I have not changed them yet.

A job with no RunAtLoad, no next-fire-date and no spawn log has exactly one honest health signal: the runs counter, checked against what the schedule should have produced. That is how I got 21 out of 21 at the top of this post, and it is the only check here that would have caught a miss. Same reasoning as a dead man's switch on a scheduled job — absence of output is the signal, and something has to be watching for it.

If you want the harness this kind of measurement runs inside — the scheduler, the guardrail prompts, the operating rules — that is what the Playbook collects.

Sources for this post: six throwaway LaunchAgents bootstrapped into gui/501 on this Mac mini (macOS 26.4.1, build 25E253) at 10:31:51Z on 12 August 2026 and booted out 8 minutes later, each logging start and end timestamps to /tmp; the run counts quoted are the runs field from launchctl print read immediately before teardown. The plist survey is a recursive parse of 888 files across /System/Library and /Library, and the exact counts are reproducible with plistlib. The sleep and DarkWake behaviour is the one part I did not measure, because this machine runs an unattended pipeline and cannot be put to sleep, so that section is quotation from Apple's documentation and forums only. The claim that com.apple.gkreport runs daily rather than weekly is inference from the shipped file plus the key-casing experiment, not an observation of that daemon. One machine, one build, one architecture, and the user domain only — the LaunchDaemon side is untested here.