---
title: "Undocumented HealthKit Errors: Handling a Case Apple Never Described"
canonical: "https://aifitnessapi.com/fix/healthkit-undocumented-errors"
cluster: "Troubleshooting"
primary_query: "undocumented healthkit error codes"
last_reviewed: "2026-09-04"
description: "Some HKError cases ship with no abstract at all. Which ones, what a name honestly lets you infer, and a handling strategy that does not invent behaviour."
publisher: "AIFitnessAPI — independent, not sponsored"
cite_as: "\"Undocumented HealthKit Errors: Handling a Case Apple Never Described\", AIFitnessAPI, https://aifitnessapi.com/fix/healthkit-undocumented-errors"
---

# Undocumented HealthKit Errors: Handling a Case Apple Never Described

> Several HKError cases are published with no description whatsoever: unknownError, errorDataSizeExceeded, errorBackgroundWorkoutSessionNotAllowed, and errorWorkoutActivityNotAllowed all appear as type properties with no abstract and no discussion. Apple documents nothing about when any of them is returned, and the oldest of them has been present since the earliest HealthKit releases without ever acquiring one. A name can legitimately point you at where to look in your own app; it cannot tell you what the framework decided. The workable strategy is to log the raw domain and code, fail soft without discarding the user's data, bound your retries, and keep your inferences labelled as inferences.

- Canonical: https://aifitnessapi.com/fix/healthkit-undocumented-errors
- Last reviewed: 2026-09-04
- Publisher: AIFitnessAPI (https://aifitnessapi.com) — independent, not sponsored
- Cite as: "Undocumented HealthKit Errors: Handling a Case Apple Never Described", AIFitnessAPI, https://aifitnessapi.com/fix/healthkit-undocumented-errors

---

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

| Case | Where Apple lists it | Published abstract | First listed on |
| --- | --- | --- | --- |
| `unknownError` | Type properties | None | iOS 8.0, watchOS 2.0 |
| `errorDataSizeExceeded` | Type properties | None | iOS 17.0, watchOS 10.0 |
| `errorBackgroundWorkoutSessionNotAllowed` | Type properties | None | iOS 17.0, watchOS 10.0 |
| `errorWorkoutActivityNotAllowed` | Type properties | None | iOS 17.0, watchOS 10.0 |

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](/healthkit-errors) 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:

| Case | A name-led place to look | What Apple confirms |
| --- | --- | --- |
| `errorDataSizeExceeded` | Whatever your app just tried to write, and how large it was | Nothing |
| `errorBackgroundWorkoutSessionNotAllowed` | Session starts happening off the foreground | Nothing |
| `errorWorkoutActivityNotAllowed` | A workout activity being refused | Nothing |
| `unknownError` | Anything; it is the catch-all by name | Nothing |

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](/fix/healthkit-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](/fix/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](/fix/healthkit-invalid-argument). Before concluding that Apple documented nothing, check whether you simply never read the abstract.

| Situation | What it is | First move |
| --- | --- | --- |
| Code has no abstract anywhere | Genuinely undocumented | Log raw, fail soft |
| Code has an abstract but no discussion | Thinly documented | Read the abstract; it constrains a lot |
| Your logs say "HealthKit error" | An observability problem | Log domain and code |
| Behaviour differs by OS version | Possibly version-specific | Segment your telemetry by version |

## 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](/methodology), and the field-level version of the same argument is in [the HealthKit error that never fires](/blog/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](/healthkit-errors). If your undocumented code arrived from a workout session, go to [workout session errors](/fix/healthkit-workout-session-errors); if it arrived from a query that returned nothing, [errorNoData](/fix/healthkit-error-no-data) covers the documented version of emptiness. And for the setup underneath all of them, see the [HealthKit integration guide](/integrate/healthkit).

## FAQ

### Which HealthKit error cases has Apple not documented?

unknownError, errorDataSizeExceeded, errorBackgroundWorkoutSessionNotAllowed, and errorWorkoutActivityNotAllowed are published as type properties with no abstract and no discussion. Apple lists their names and the platforms they exist on, and nothing more. Most of the described cases, by contrast, appear in Apple's accessing-errors listing with an abstract and often a discussion paragraph.

[Permalink](https://aifitnessapi.com/fix/healthkit-undocumented-errors#faq-1)

### Can I infer what errorDataSizeExceeded means from its name?

You can use the name to decide where to look, and no further. A sensible investigation is to examine what your app just tried to write and how large it was. Turning that into a user-facing message about a size limit invents both a mechanism and a threshold that Apple has never published.

[Permalink](https://aifitnessapi.com/fix/healthkit-undocumented-errors#faq-2)

### How should my app handle an unknown HealthKit error code?

Log the raw domain and numeric code together with the operation and type identifier, keep the data you were trying to write and mark it unsynced, allow a small bounded number of retries, then stop. Alert on clusters rather than single occurrences, and never map an undocumented code to a confident explanation in your UI.

[Permalink](https://aifitnessapi.com/fix/healthkit-undocumented-errors#faq-3)