CloudKit public database: unknownItem despite earlier Console visibility — interpreting fetch and authorization diagnostics

We are investigating one completed CloudKit Development test in a separate test container using only synthetic data.

Shortly before an iOS client attempted to fetch a record from the public database’s default zone, that synthetic record was visible in CloudKit Console.

The native client returned:

  • CKErrorDomain code 11 (unknownItem)
  • Underlying CKInternalErrorDomain code 2003
  • Sanitized diagnostic: record_not_found
  • No record

We verified that the client’s intended container, database, zone and record name matched the reference.

A CloudKit Console event showed RecordFetch, operation-level SUCCESS, and approximately 171 ms execution time. However:

  • The event was correlated by context and timestamp, not by a directly matched client operation or request ID.
  • The available event did not expose a per-record result or an authorization decision.
  • Earlier Console visibility does not establish availability or client access at the exact time of the fetch.

The cause therefore remains unresolved. We have not established that a permissions restriction caused the error.

We understand that Apple documents unknownItem for a nonexistent record and permissionFailure for insufficient permission to fetch or save data. We also understand that operation-level success and per-record fetch success are distinct.

Our questions are:

  1. Can a public-database read restriction cause an existing record to be reported to a native client as unknownItem, rather than permissionFailure? If so, is this documented behavior?
  2. What does operation-level SUCCESS mean specifically for a RecordFetch event in CloudKit Console? Can that event still contain an unsuccessful individual record lookup?
  3. Which supported diagnostics can distinguish a missing or unavailable record from an authorization-based visibility restriction?
  4. Can Apple determine the authorization outcome of an existing request from retained diagnostics, and which correlation identifiers are required?
  5. What evidence is sufficient to verify server-enforced read restrictions in Development while preserving the existing roles and leaving production untouched?

We are seeking clarification of the existing evidence, not proposing another reproduction attempt. No customer data, credentials or production records are involved.

unknownItem indicates the requested item does not exist, which can happen when the specified record ID doesn't really exist, or the record is not yet indexed. permissionFailure indicates the user has no access to the item. For a public database, a custom security role can be used to prevent a user from accessing a record type. If you see an error that should have been permissionFailure but is reported as unknownItem, I'd suggest that you file a feedback report.

CloudKit reports SUCCESS for an operation when the request goes through without triggering any operation-level eror, such as invalid authentication token, quota exhaustion, a missing/invalid zone reference, bad request format, or internal server errors. It's possible that a successful operation contains a per-record error.

To get the detailed error info, you can use the CloudKit native APIs, which I think is what you are doing. As an example, records(for:desiredKeys:) returns a dictionary that contains the fetched results by record ID, and the result can be a fetched record, or a per-record error, with an detailed CKError code.

By looking into the error code, you should be able to tell if it is that the record doesn't exist (unknownItem), or the user doesn't have the access to the record (permissionFailure)

For question 4 and 5, I'm not quite clear what they are asking, probably because of the terms ("retained diagnostics, for example). What I can say is that a CloudKit production environment is completely separated from the development environment. Only after you deploying the schema changes, would the additions on the development environment be pushed to the production environment.

Best,
——
Ziqiao Chen
 Worldwide Developer Relations.

Thank you for clarifying the distinction between unknownItem and permissionFailure, and between operation-level SUCCESS and per-record results. We do not regard the existing SUCCESS event as proof that the record was fetched or that access was granted. The cause of our original unknownItem remains unresolved.

To clarify questions 4 and 5:

  1. By retained diagnostics, we mean the client error details and CloudKit Console event information already saved from the completed synthetic Development test. Our Console event was matched by time and context, not by a directly matched client operation/request ID. Which specific identifiers, if present in those existing records, would Apple need to correlate the request and determine its authorization outcome retrospectively? If the existing information cannot establish that outcome, please confirm that limitation.

  2. We are asking what evidence demonstrates a server-enforced read denial under the existing public-database security roles. Would a per-record CKError.permissionFailure, tied to the exact container, environment, record type and record ID, establish that denial, or is additional supported evidence required? We understand that unknownItem alone does not establish a permissions restriction.

We understand that Development and Production are separate. We are seeking interpretation of the existing evidence at this stage; no role changes, schema deployment or new reproduction is being performed.

Thank you.

Thanks for the clarification.

Regarding 4, you can reproduce your issue by using CKFetchRecordsOperation in your client side code, which provides you an operation ID (operationID) that matches the CloudKit Console log entry.

Regarding 5, permissionFailure doesn't convey the details about the security role, if that is the cause. Did you get an permissionFailure error at all? If not, I would put it aside for now.

The following may be worth doing:

  • Check if you use the right record ID and make sure you predicate (NSPredicate), if any, doesn't filter out anything. You can do so by trying to query with the same record ID and predicate in CloudKit Console, and see if it returns you the right record.

  • Check if the recordName field of your target record type is QUERYABLE. If not, add that, and try again.

  • For debugging purposes, completely remove your record type, and then add it back, set up the QUERYABLE index for the type, and then add records. In some corner cases, CloudKit may not index your database (yet), and doing this will trigger the indexing process.

Best,
——
Ziqiao Chen
 Worldwide Developer Relations.