HealthKit Background Delivery Not Working: Why Your Observer Never Fires

The code looks right. There is an HKObserverQuery, there is a call to enableBackgroundDelivery, the app reads steps perfectly when it is open, and the update handler has never once run while the phone was in a pocket. Almost every instance of this is one of a small set of documented gates, and four of them are stated in a single paragraph of Apple's reference page that most people skim past on the way to the code sample.

Work them in order. Each one is cheap to check and each one, on its own, is sufficient to produce total silence.

Gate 1: the entitlement you probably do not have#

Apple's requirement is unambiguous. For iOS 15 and watchOS 8 and later, you must enable HealthKit Background Delivery by adding the com.apple.developer.healthkit.background-delivery entitlement to your app, and if your app does not have it, enableBackgroundDelivery(for:frequency:withCompletion:) fails with an HKError.Code.errorAuthorizationDenied error.

Two things make this the number-one cause. First, the entitlement is documented as a Boolean whose default value is false — it is available from iOS 15, iPadOS 15, watchOS 8 and visionOS 1, but you get nothing unless you add the key deliberately. Second, the error is easy to miss, because Apple hands it to you through a completion block whose arguments almost everybody throws away:

healthStore.enableBackgroundDelivery(for: stepType, frequency: .hourly) { success, error in
    // Both of these are load-bearing. Log them.
    if let error {
        // errorAuthorizationDenied here means the ENTITLEMENT is missing,
        // not that the user denied anything.
        log.error("background delivery not enabled: \(error)")
        return
    }
    log.info("background delivery enabled: \(success)")
}

Note the wording trap in the error name. errorAuthorizationDenied reads like a permission refusal, and permission refusal in HealthKit is a topic with its own long list of surprises — covered in HealthKit authorization denied. Here it means nothing of the kind. The user is not involved.

Gate 2: the Simulator will never do this#

Apple prints the same sentence twice, once on the enableBackgroundDelivery reference and again on the HKObserverQuery reference: background server queries are not supported on the Simulator, and you should be sure to test your background queries on a device.

There is no flag and no partial credit. If your only evidence that background delivery does not work is a Simulator session, you have no evidence at all. This also means a Simulator-based CI pipeline covers none of this path, which is the honest boundary drawn in testing a HealthKit integration. Move to real hardware before you change a line.

Gate 3: the query does not exist when the wake arrives#

This one produces the most confusing symptom, because everything looks correct in the foreground.

Apple documents the launch sequence directly: as soon as your app launches, HealthKit calls the update handler for any observer queries that match the newly saved data, and if you plan on supporting background delivery, you should set up all your observer queries in your app delegate's application(_:didFinishLaunchingWithOptions:) method. Apple's own explanation for why is the part to internalise — registering there ensures the queries are instantiated and ready to use before HealthKit delivers the updates.

A background wake launches your process. If your observer is created inside a view controller's setup, or behind a feature flag that resolves after a network call, or on first navigation to a screen, then at the moment HealthKit tries to deliver there is no matching query in the process and the delivery goes nowhere. In the foreground you always happen to have visited that screen, so it always works.

Gate 4: three missed acknowledgements and you are switched off#

Apple's completion-handler documentation contains the single most consequential sentence in this whole area. You must call the block as soon as you are done processing the incoming data; if you do not, HealthKit continues to attempt to launch your app using a backoff algorithm, and if your app fails to respond three times, HealthKit assumes your app cannot receive data and stops sending you background updates.

Read that as a strike count, not as a retry policy. The handler is the heartbeat that keeps the channel alive, and the place people forget it is the error path — a thrown error, an early return on a nil unwrap, an upload that times out before the line is reached. Three of those and the install is done receiving background deliveries, which is exactly the "it worked last week" report you will get from QA.

let observer = HKObserverQuery(sampleType: stepType, predicate: nil) { _, completionHandler, error in
    // Acknowledge on EVERY path, including the failure branch.
    defer { completionHandler() }

    if error != nil { return }
    // Persist locally first, then acknowledge, then upload asynchronously.
    ingestFromPersistedAnchor()
}
healthStore.execute(observer)

Symptom to cause#

The four things that look like failures and are not#

The observer is a doorbell, not a parcel. Apple is explicit that the update handler does not receive any information about the change, just that a change occurred, and that you must execute another query — an HKSampleQuery or an HKAnchoredObjectQuery — to access the changes. An anchored object query is usually the right second query, because Apple describes it as combining a snapshot of what is currently stored with a long-running query that responds to updates, returning an anchor corresponding to the last sample or deleted object it saw so subsequent runs return only newer objects.

frequency is a maximum, not a schedule. Apple defines it as the maximum frequency of the updates, waking your app from the background at most once per time period specified. HKUpdateFrequency offers immediate, hourly, daily and weekly, described respectively as launching your app every time a change is detected, at most once an hour, at most once a day, and at most once per week. Nothing in that documentation promises a minimum rate.

Some types are capped no matter what you ask for. Apple states that some sample types have a maximum frequency of hourly and that the system enforces this frequency transparently, giving step count on iOS as the example. In watchOS most data types are hourly-capped too, with a named exception list that can reach immediate — high heart rate, low heart rate and irregular heart rhythm events, environmental and headphone audio exposure events, low cardio fitness events, number of times fallen, VO2 max, handwashing and toothbrushing events. On watchOS there is also a budget: background updates share an allowance with WKApplicationRefreshBackgroundTask, four an hour, conditioned on the app having a complication on the active watch face.

A locked phone can turn a successful wake into an empty read. Apple documents that the device encrypts the HealthKit store when the user locks it, so your app may not be able to read data from the store when it runs in the background. Writes still work and are cached until unlock. So a wake that produces nothing is not proof the user did nothing — and if your query comes back empty in the foreground too, that is a different investigation entirely, laid out in HealthKit returning no data.

After the gates#

Once delivery is genuinely working, the remaining problem is that no amount of correct code makes a wake happen. Apple publishes a ceiling and a shutdown rule; it publishes no minimum rate, no latency figure and no delivery guarantee. That means a pipeline whose correctness depends on being woken is a pipeline that will eventually be wrong. Pair every wake with a foreground reconciliation and a server-side staleness check, so a missed delivery costs latency rather than a wrong number — the design is worked through in background sync that does not depend on the phone waking up.