Skip to main content
Connect your coding agent to the PoolKit MCP server 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.
  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.

​
The key is refused

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 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 with your app ID (from the dashboard), the SDK version and, if you can, a run ID from the dashboard. Never send a key.