HealthSave troubleshooting: the real issues, and the real fixes
Most HealthSave problems resolve with two moves: update to the latest version, and if a metric is stuck, run Reset Sync Progress followed by Backfill Past Data. This page documents the issues users have actually reported — including the bugs that were ours — what caused each one, and exactly what to do. If your issue isn't here, email support@healthsave.app; real threads are how this page grows.
"A blank screen comes over and blocks the app"
Reported as: "a blank screen that comes over and blocks the app", "a black screen comes from the bottom", a sheet that can't be dismissed, sometimes several in a row.
This was our bug, and it's fixed (1.5.4). The app was re-requesting Apple Health authorization on every launch and every return to foreground. That permission request is a system sheet drawn by iOS — and when it fired at an unstable moment (cold launch, right after another dialog), it could render blank and un-dismissable, then fire again on the next launch. It reproduced almost exclusively on iPhone 17 Pro and Pro Max.
What to do:
- Update HealthSave to the latest version from the App Store.
- If a blank panel still flashes once after updating, reboot the phone — that clears the stale sheet state.
Your data was never at risk. The blank sheet was a display-layer failure; sync kept running underneath it. Users who hit this confirmed their Grafana dashboards and Home Assistant sensors kept receiving data the entire time.
"A previous upload failed permanently for: [metric]"
Reported as: "syncing continuously fails across 8 different groups of data", "Outbox pending seems to always stick at 1", "New samples of this type are not being read until it's cleared."
What it means: your server rejected (or could not fully write) one batch of that metric. HealthSave stops queueing new samples of that type on purpose — pushing newer samples past a failed batch would corrupt ordering on your backend.
The fix is two taps: Reset Sync Progress, then Backfill Past Data. That discards the poisoned batch, re-reads the metric's history, and resumes normal sync.
If you run your own backend, one root cause is worth checking: a request-size cap that kills oversized POSTs by dropping the connection instead of answering. A multi-year workout backfill can produce a large batch; if your reverse proxy or server destroys the socket, HealthSave sees a network failure — which is retryable — and retries the same batch forever. Return a clean HTTP 413 (or raise the body limit; one user settled on 64 MB) and the loop breaks properly. This exact case was diagnosed by a self-hosting user whose proxy had a byte cap: "HealthSave then correctly retried — but retried the exact same oversized batch, which failed the exact same way, forever."
A metric is stuck on "Sending…" forever
Cumulative metrics (Step Count, Cycling Distance, Flights Climbed, Basal Energy) could show "Sending…" indefinitely even though the data had already landed on the server. This was a status-display bug — a missing final state transition — not a data problem, and it's fixed. Update to the latest version; if the label persists, Reset Sync Progress clears it. If you want certainty, check your backend: the samples are almost certainly already there (one user verified 1.6M+ samples had ingested correctly while the UI said "Sending…").
One metric never syncs while every other type works
Reported as: "body_mass never appears in any batch sent to my server. Not once, across many syncs."
Two causes account for essentially all of these:
- The per-category permission was never granted. Apple Health permissions are per category, and the grant list is long. Open the Health app → profile picture → Privacy → Apps → HealthSave and verify the category is on. This was the entire story behind a "missing" blood-pressure feature — the export existed; the permission wasn't granted.
- The metric's only samples come from a stale source. An old smart scale, a retired app, or a device account that was migrated (for example an ancient Fitbit scale) can leave a metric with no valid recent samples. Check the metric inside the Health app itself: if Apple Health shows nothing recent, there's nothing for HealthSave to read. Our Fitbit data guide covers getting legacy tracker data back into a usable state.
The full list of what HealthSave can export — with the exact identifier each metric uses in your CSV/JSON — is at healthsave.app/metrics/.
Background sync runs at odd times
iOS schedules background work opportunistically: it decides when apps get execution windows based on charging, usage patterns, and battery state. HealthSave requests regular background sync; iOS grants the actual timing. Syncs bunching up overnight on the charger is the system working as designed, not a defect.
One honest product decision behind this: iOS does offer a way to wake apps more often — significant-location-change triggers. We rejected it, because it requires the "Always" location permission. A health-data app asking for permanent location access to speed up sync is not a trade we're willing to make. If you need low-latency delivery, open the app; a foreground sync runs immediately.
Still stuck?
Email support@healthsave.app with your app version and, if you self-host, what your backend is (reference hub, community backend, or custom). The threads on this page were all answered directly — yours will be too.
Related
- Every metric HealthSave exports (with export identifiers)
- Build a custom REST API over your Apple Health data
- Push live Apple Health metrics into Home Assistant
- Back up 10+ years of Apple Health history
- HealthSave support