> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pool.day/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> The problems developers hit most with PoolKit, and how to fix each.

Connect your coding agent to the [PoolKit MCP server](https://docs.pool.day/mcp.md) and ask it: `get_setup_status` checks most of this page against what Pool's service has seen from your builds, and `explain_failure_code` explains any error.

## Results are empty

1. **Is there a grant?** Indexing starts only once a grant exists. Call `requestAccess` first, then query with that grant.
2. **Is indexing done?** An empty answer means "nothing there" only when `result.coverage.isComplete`. Otherwise show progress from `coverage.indexedAssets` and `knownAssets`.
3. **Is the window right?** The default index window covers three months back. Older photos need `.everything` or a longer span in [IndexOptions](https://docs.pool.day/indexing.md#choose-what-is-indexed).
4. **Does the grant cover it?** A grant for `.products` never returns places, whatever the question says. Videos also need `.videos` in `PoolConfiguration.sources`.
5. **Limited library access?** When the person picked only some photos, PoolKit sees only those. `result.coverage.permission` says `limited`.
6. **In the Simulator?** Drag photos and screenshots into the Simulator, or use the [test fixtures](https://docs.pool.day/testing.md).

## The key is refused

| Symptom | Cause | Fix |
| - | - | - |
| `PoolError.invalidAppKey` | The key is mistyped, revoked, or past the end of a rotation | Copy a live key from the dashboard, or rotate and ship the new one. |
| 403 `bundle_not_allowed` | The build's bundle ID is not on the app | Add it in the dashboard, including the debug bundle ID if it differs. |
| 403 `app_pending` | Another developer's app listed that bundle ID first | Pool approves it by hand; write to [hey@pool.day](mailto:hey@pool.day). |
| 403 `app_disabled` | The app is turned off in the dashboard | Turn it on. |
| 401 `attestation_required` in debug builds | App Attest is enforced and a live key is in a debug build | Use the test key in debug builds. Test keys are never enforced. |

A refused key stops only cloud calls. The on-device engine keeps working, and PoolKit tries the key again the next time the app opens.

## Indexing is slow or stops

* **The first index takes time.** A large library takes minutes in the foreground. Register [background indexing](https://docs.pool.day/indexing.md#while-the-app-is-closed) so iOS can carry on while the app is closed.
* **Runs end with `endedByIOS`.** iOS gives background tasks a few minutes; the next run carries on. This is normal on large libraries.
* **Models still downloading.** The engine's models, about 375 MB, download on Wi-Fi. Until they arrive, search works from text and labels. `pool.sources.status()` shows the download.
* **iCloud photos.** Photos only in iCloud are skipped unless `allowsNetworkDownloads` is on.
* **Low Power Mode or a hot phone.** PoolKit slows down rather than drain the battery.

Turn on `sendsRunReports` to see how runs end, per device, in the dashboard.

## Places or people show nothing

* Places appear once PoolKit has seen at least 30 located photos on 10 days, so it knows where home is. Nothing near home is ever shown.
* Place names need a network that is not metered, unless `allowsCellular` is on. Offline, only the city is named.
* People need both the `.people` category in a grant and `IndexOptions.people = true`. Only photos with a clear face count.

## Cloud assist answers 429

* `quota_exceeded`: the app used its month's cloud assist units or connected installs. Check usage in the dashboard or with `get_usage`.
* `cloud_assist_disabled`: cloud assist is off for this app.
* `rate_limited`: one install sent requests too fast. PoolKit waits by itself.

## Still stuck

Write to [hey@pool.day](mailto:hey@pool.day) with your app ID (from the dashboard), the SDK version and, if you can, a run ID from the dashboard. Never send a key.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.