Your Rork Max Health App Misses Overnight Steps — Designing Background Delivery When HKObserverQuery Dies Silently

Stop the observer from dying after one shot with the completion handler

Stage three, the observer query, is where the silent failure most often happens. The HKObserverQuery handler receives a completionHandler (HKObserverQueryCompletionHandler). If you don't call it, the system decides your processing hasn't finished and stops waking your app in the background from then on. In the foreground it works even if you forget, so you can't catch it until release.

extension HealthObservation {
    func startObserver() {
        let query = HKObserverQuery(
            sampleType: stepType,
            predicate: nil
        ) { [weak self] _, completionHandler, error in
            guard let self else { completionHandler(); return }
            if let error {
                healthLog.error("observer error: \(error.localizedDescription)")
                completionHandler()   // always call, even on error
                return
            }
            // delegate the actual fetch to an anchored query
            Task {
                await self.fetchIncremental()
                healthLog.info("observer fired, incremental fetched")
                completionHandler()   // call after the fetch completes
            }
        }
        store.execute(query)
    }
}

Two things matter here. First, call completionHandler() exactly once on every path — success, failure, and early return. Second, the observer itself carries no data. It only hands you the signal that "something changed." The actual delta fetch is done separately with an anchored query.

Pair it with HKAnchoredObjectQuery to fetch only the delta

If you re-scan the entire history every time the observer fires, you'll exhaust your background execution time fast. HKAnchoredObjectQuery returns an anchor marking the last position, so if you persist it, next time you fetch only what was added. Neglect to persist the anchor and every run becomes a full fetch, which gets throttled — and you're back to the "occasionally missing" symptom.

extension HealthObservation {
    private var anchorKey: String { "health.anchor.stepCount" }
 
    private func loadAnchor() -> HKQueryAnchor? {
        guard let data = UserDefaults.standard.data(forKey: anchorKey) else { return nil }
        return try? NSKeyedUnarchiver.unarchivedObject(
            ofClass: HKQueryAnchor.self, from: data)
    }
 
    private func saveAnchor(_ anchor: HKQueryAnchor) {
        let data = try? NSKeyedArchiver.archivedData(
            withRootObject: anchor, requiringSecureCoding: true)
        UserDefaults.standard.set(data, forKey: anchorKey)
    }
 
    func fetchIncremental() async {
        await withCheckedContinuation { continuation in
            let query = HKAnchoredObjectQuery(
                type: stepType,
                predicate: nil,
                anchor: loadAnchor(),
                limit: HKObjectQueryNoLimit
            ) { [weak self] _, samples, _, newAnchor, error in
                if let error {
                    healthLog.error("anchored error: \(error.localizedDescription)")
                }
                if let newAnchor { self?.saveAnchor(newAnchor) }
                let count = samples?.count ?? 0
                healthLog.info("incremental samples: \(count)")
                // reflect samples into your own store here
                continuation.resume()
            }
            store.execute(query)
        }
    }
}

UserDefaults is fine for the anchor, but sharing it through an App Group lets your widget render off the same delta baseline. Running several small apps, I've found that pointing the anchor's storage at shared storage from the start makes later expansion much easier.

Three gaps Rork Max's generated code can't fill

Rork Max generates the Swift query logic well enough from natural language. But making background delivery hold on a real device requires configuration outside the code, and the AI's output alone won't fill it. Three things I verify by hand every time.

First, the Info.plist purpose strings. Put NSHealthShareUsageDescription (read) and, if you write, NSHealthUpdateUsageDescription in with concrete wording that won't be rejected in review. If these are empty, the permission dialog never appears on a real device.

Second, capabilities. Enable the HealthKit capability, and if you use background delivery confirm it's active on the HealthKit side (paired with the enableBackgroundDelivery call), not via Background Modes.

Third, extra setup when workout integration is needed. To receive high-frequency updates during a workout, enable Workout processing under Background Modes. Steps alone don't need it, but you will the moment you extend to real-time heart rate.

How to reproduce "missing only while closed"

This class of bug never reproduces in the foreground. My routine: send the app fully to the background (return to the home screen), separately add real data via the iPhone Health app or a workout, then open the app tens of minutes later and check whether observer fired appeared in the logs while it was closed.

If background delivery enabled shows up but observer fired never appeared while closed, the cause is usually the observer's registration timing. An observer query has to be executed again on every app launch; if you don't re-arm it early — around the application(_:didFinishLaunchingWithOptions:) equivalent — the query won't exist when the system launches you in the background, and you drop the update. Rork Max's generated code tends to start the observer after the screen appears, so hoisting it to right after launch is the move that actually holds on a real device.

For your next step, wire the HealthObservation above so bootstrap() runs right after launch, leave it on a real device overnight, and check the logs. Building a state where the logs show at a glance which of the three stages broke is the fastest path to putting this silent failure behind you.