Every HealthKit error code
17 HKError.Code cases · read from Apple’s documentation on 2026-08-28
The error most people come here looking for does not exist: a denied HealthKit read raises nothing at all. Apple reports refusal only on writes, so an empty result is deliberately ambiguous between “no data” and “no permission”.
HKError.Code, which has 17 cases. Two things about that set surprise people. The first is that read denial is not one of them — Apple raises errorAuthorizationDenied when your app tries to save, and a refused read simply returns your own app’s data and nothing else. The second is that Apple does not publish the numeric values, so the code in your crash log cannot be matched to a name from the documentation. Both are stated below rather than smoothed over.The silent failure
Apple’s description of errorAuthorizationDenied is The user hasn’t given the app permission to save data
, and its discussion adds that the error occurs only when your app attempts to save data
. There is no equivalent for reading. If the user refuses read access, your query succeeds and returns only what your own app wrote into HealthKit — which for a new install is nothing.
This is intentional: telling an app that a read was refused would itself leak that the user has something to hide. The consequence for your code is that an empty result can never be presented as a statement about the user. Design the empty case as we can’t see this
, never you have no data
. Our HealthKit returns no data and authorization denied pages work through the diagnosis.
The cases Apple documents
errorHealthDataRestricted
A Mobile Device Management (MDM) profile restricts the use of HealthKit on this device.
Because an MDM profile can disable HealthKit on a managed device, always verify that the current device supports HealthKit by calling before calling any other HealthKit methods. If HealthKit is restricted (for example, in an enterprise environment), the methods fail with an error.
iOS 8.0+ · Apple docs
errorDatabaseInaccessible
The HealthKit data is unavailable because it’s protected and the device is locked.
This error occurs when your app queries for HealthKit data while the device is locked. You can, however, still save data. This data is saved into a temporary file, which is merged with HealthKit’s data when the user unlocks their device.
iOS 8.0+ · Apple docs
errorAnotherWorkoutSessionStarted
Another app started a workout session.
This error occurs whenever a second workout session is started. Apple Watch only runs one workout session at a time. If the user begins a second workout session in a different app, the original session receives this error message and then ends. The second session then starts.
iOS 9.0+ · Apple docs
errorUserExitedWorkoutSession
The user exited your application while a workout session was running.
Workout sessions end when the app goes into the background.
iOS 9.0+ · Apple docs
errorNoData
Data is unavailable for the requested query and predicate.
This error indicates that no data exists that corresponds to a particular query, so the system can’t calculate the query’s result. queries return this error when HealthKit can’t return the data needed to calculate the statistics.
iOS 14.0+ · Apple docs
errorNotPermissibleForGuestUserMode
The app attempted to write HealthKit data while in a Guest User session in visionOS.
iOS 18.0+ · Apple docs
The cases Apple ships undocumented
4 cases carry a declaration and nothing else — no description, no discussion — as of 2026-08-28. They can still be returned to your app.
errorBackgroundWorkoutSessionNotAllowedApple docserrorDataSizeExceededApple docserrorWorkoutActivityNotAllowedApple docsunknownErrorApple docs
Questions
Which HealthKit error tells me the user denied a read?
None of them, and that is the single most misunderstood thing about HealthKit permissions. Apple's own description of errorAuthorizationDenied says it occurs when the app attempts to save data. A denied read is not reported as an error at all — the query succeeds and returns only the data your own app previously wrote, which for most apps is nothing. So an empty result set is ambiguous by design: it means either the user has no such data or the user refused you access, and HealthKit deliberately will not tell you which. Never render 'no data' as a factual claim about the user; render it as 'we cannot see this'.
What is HealthKit error code 5 — how do I map a number to a name?
You cannot, from anything Apple publishes. Crash logs and NSError descriptions surface the numeric code — "Error Domain=com.apple.healthkit Code=5" — but Apple's documentation for HKError.Code lists the 17 cases without their raw integer values, and the order the documentation lists them in is not declaration order, so the position of a case in the list tells you nothing about its number. We could publish a guessed mapping and it would look authoritative; instead we publish the named set and this caveat. To identify an error in your own code, switch on HKError.Code rather than comparing integers.
Are there HealthKit errors Apple ships with no documentation?
Yes — 4 of the 17 cases carry a declaration and nothing else as of our 2026-08-28 read: errorBackgroundWorkoutSessionNotAllowed, errorDataSizeExceeded, errorWorkoutActivityNotAllowed, unknownError. They compile and they can be returned to you, but Apple's reference does not say what triggers them or what you should do about it. If you hit one, anything you conclude is inference from observed behaviour rather than documented contract.
Every case, description and discussion above is read from Apple’s published documentation on 2026-08-28 by scripts/fetch-healthkit-identifiers.mjs. The type reference lives at every HealthKit type identifier. Compiled by AIFitnessAPI; Apple’s documentation remains the authority.