HealthKit errorHealthDataRestricted: An MDM Profile Turned HealthKit Off

Your app works on every device in the office and fails on every device at the customer. The calls come back with errorHealthDataRestricted, the user swears they granted permission, and the Health app looks normal to them. Nothing in your code caused this and nothing in your code will undo it: an administrator turned HealthKit off on that device.

What Apple documents#

Apple's documentation states the abstract as: "A Mobile Device Management (MDM) profile restricts the use of HealthKit on this device." The discussion adds the mechanism and the defence:

Because an MDM profile can disable HealthKit on a managed device, always verify that the current device supports HealthKit by calling [the availability check] before calling any other HealthKit methods. If HealthKit is restricted (for example, in an enterprise environment), the methods fail with an [errorHealthDataRestricted] error.

The bracketed labels are ours — Apple links those symbols inline and the link text does not survive as plain text. The important word in the quote is methods, plural: the restriction is not scoped to one type or one operation, it is the framework being switched off underneath you.

Note also that Apple gives this case the same instruction it gives errorHealthDataUnavailable: check before calling anything else. Two different causes, one guard. That is convenient for your code and misleading for your copy, because the two conditions call for completely different things to say to the person holding the device.

You detect it; you do not fix it#

This is the honest frame for the whole page. Everything you can do lives in two places: detect the condition before you build UI on top of it, and tell the truth about it afterwards.

Where it actually bites#

Corporate wellness is the obvious case, and the one where it is most expensive to discover late. You ship a step-challenge or benefits-linked app, the employer distributes it through their management system to managed handsets, and the same profile that pushed your app has HealthKit disabled. Every automatic data path in your product is dead on arrival for that population, while working flawlessly in your own testing. If that is your market, read this alongside building a corporate wellness app before you design the onboarding.

Two adjacent situations to keep separate in your head:

• Managed devices in healthcare, education, and finance. Restriction may be a blanket policy rather than a decision about your app specifically.
• Shared or borrowed devices. A device someone else administers is not a device your user controls, whatever the login says.

And one genuinely different failure that produces the same case name: on Apple Vision Pro, our HealthKit authorization denied guide records Apple's statement that a write attempted during a Guest User session fails with errorNotPermissibleForGuestUserMode, or with errorHealthDataRestricted on apps running in iOS 17. So a restricted error on that platform may be a guest session rather than a management profile — the details are in Guest User mode.

Diagnosis order#

1. Log the exact code. errorHealthDataRestricted and errorHealthDataUnavailable arrive at the same catch block and mean different things. If you collapse them into one "HealthKit unavailable" branch, your support team can never tell a corporate policy from an unsupported device.
2. Ask one question in your support flow. "Is this device managed by your employer or school?" resolves most of these tickets in a single reply, and no log line does it faster.
3. Check the population, not the device. If failures cluster by employer, domain, or enrolment cohort, you are looking at policy. If they are scattered across consumer installs, look at capability and setup instead.
4. Stop retrying. A restriction does not lift because you asked again in an hour. Retry logic here just consumes background execution time you could spend on the users who can actually sync — see background sync for where that budget goes.

What to build instead, as practice#

• A distinct state, not an error toast. Model "HealthKit restricted on this device" as a real state in your app alongside "not connected" and "connected", and render it as an explanation rather than a failure.
• Copy that points at the right person. Something like: this device's management profile has Health access turned off, so automatic tracking is unavailable; your IT administrator controls this setting. Do not send the user to Settings for a switch that is not there, and do not imply they did something wrong.
• A manual path that keeps the product usable. Manual logging, a connected sensor, or camera-based tracking keeps the core loop alive without the store. Losing automation should not mean losing the app.
• Admin-facing documentation. If you sell to employers, the buyer is the person who can change the policy. A short page telling their administrator which capability your app needs is worth more than any in-app message.
• Honest analytics. Count restricted devices separately from unavailable ones and from denied permissions. Three causes, three numbers; blending them hides a fixable commercial problem inside an unfixable technical one.

Symptom to action#

Where to go next#

Apple's full wording for every case in the enum is collected in the HealthKit error reference, and the cases Apple ships with no description at all are handled in undocumented HealthKit errors. If you are still wiring the happy path, the HealthKit integration guide covers the setup this error interrupts.