Undocumented HealthKit Errors: Handling a Case Apple Never Described

Some HealthKit errors have no documentation. Not thin documentation, not documentation in a different place — no published description at all. Apple lists the case, the platforms it exists on, and nothing else. If you have landed here holding a code you cannot look up, the goal of this page is to get you to a safe handling strategy without either of you inventing behaviour that Apple never described.

Which cases have no description#

Two things stand out. One of the oldest cases in the enum is an undescribed one — unknownError goes back to the earliest listed releases and has still never acquired an abstract. And the grouping matters: most of the described cases sit in Apple's accessing-errors listing with abstracts and, often, discussion paragraphs, while these four appear as type properties with the name as the entire published content. Our HealthKit error reference marks this distinction on every case rather than hiding it behind plausible-sounding prose.

What a name lets you infer, and what it does not#

It is reasonable to let a name direct your investigation. It is not reasonable to let it write your error messages, your retry policy, or your documentation. The honest form of the inference looks like this:

Every cell in the middle column is a hypothesis for you to test in your own app, on your own data, on a device you control. None of them is a fact about the framework. The two workout cases are handled alongside their documented siblings in workout session errors, where the contrast between a case with a discussion paragraph and a case with nothing at all is easiest to see.

The handling strategy: log raw, fail soft#

• Log the domain and the numeric code, always. Not a mapped label, not a friendly string — the raw values, alongside the operation, the type identifier, and the size or shape of whatever you passed. When Apple documents the case later, or when the pattern becomes obvious across your install base, those logs are the only thing that will let you go back and interpret past failures.
• Never map an unknown code to a confident message. "Your workout was too large to save" is a claim about the framework you cannot support. "This didn't save — we've logged the details" costs you nothing and is true.
• Fail soft and keep the payload. Whatever you were trying to write still exists in your app. Hold it, mark it unsynced, and let a later attempt or a support export recover it. Discarding user data on the strength of an undocumented code is the one genuinely unrecoverable mistake available here.
• Bound your retries. Allow a small, bounded number of attempts in case the cause was transient, then stop and record the outcome. Cases that are structural rather than environmental will fail identically forever — the transient/terminal split is worked through in HealthKit database inaccessible.
• Reduce the payload as an experiment, not a fix. If you suspect size, try a smaller write and see. Write down what you observed and label it as your observation.
• Alert on the shape, not the instance. One unknown code is noise. A sudden cluster on one OS version, one device family, or one code path is a signal worth a person's attention, and it is why the raw code matters more than the friendly message.

Do not confuse "undocumented" with "unclassified"#

There is a second, larger category worth separating: cases Apple does document, which teams treat as mysterious because their logging collapsed everything into one branch. errorInvalidArgument has a one-line abstract and no discussion, but that one line tells you it is a programming error rather than an environmental one, and the diagnosis has a real procedure — see invalid argument. Before concluding that Apple documented nothing, check whether you simply never read the abstract.

Writing about it honestly#

If your team keeps an internal runbook, hold it to the same rule this site uses: state what the vendor documents, attribute it, and mark your own inferences as inferences. A runbook that says "errorDataSizeExceeded occurs when a sample exceeds the limit" invents both a mechanism and a limit; a runbook that says "no published description; observed in our app when writing large batches, unconfirmed" stays useful and stays true. How we apply that standard across the site is set out in our methodology, and the field-level version of the same argument is in the HealthKit error that never fires.

Where to go next#

Every case in the enum, with Apple's own wording where it exists and an explicit gap where it does not, is in the HealthKit error reference. If your undocumented code arrived from a workout session, go to workout session errors; if it arrived from a query that returned nothing, errorNoData covers the documented version of emptiness. And for the setup underneath all of them, see the HealthKit integration guide.