SyncEngine drops records on transient CloudKit errors (serviceUnavailable, requestRateLimited) instead of re-queuing

[mario-luis-dev]

Description

When CloudKit returns transient errors like .serviceUnavailable (CKError 6/2009) or .requestRateLimited (CKError 7/2062)for individual record saves, the SyncEngine silently drops those records from the sync queue. They are never retried, causing permanent data loss from the sync perspective.

Location: SyncEngine.swift around line 1784 (v1.6.1, commit da3a94e)

  case .networkFailure, .networkUnavailable, .zoneBusy, .serviceUnavailable,                                               
    .notAuthenticated, .operationCancelled,                                                                                
    .internalError, .partialFailure, .badContainer, .requestRateLimited, .missingEntitlement,                              
    .invalidArguments, .resultsTruncated, .assetFileNotFound,                                                              
    .assetFileModified, .incompatibleVersion, .constraintViolation, .changeTokenExpired,                                   
    .badDatabase, .quotaExceeded, .limitExceeded, .userDeletedZone, .tooManyParticipants,                                  
    .alreadyShared, .managedAccountRestricted, .participantMayNeedVerification,                                            
    .serverResponseLost, .assetNotAvailable, .accountTemporarilyUnavailable:                                               
    continue   // ← record is NOT re-queued       

Compare with .batchRequestFailed at line 1781 which correctly re-queues:

  case .batchRequestFailed:                             
    newPendingRecordZoneChanges.append(.saveRecord(failedRecord.recordID))                                                 
    break

The same pattern exists for failed record deletes (around line 1820).

Steps to reproduce

1. Register multiple tables with SyncEngine (in my case ~25 tables including junction tables)
2. Save a record that triggers writes across several tables (e.g., a parent record + genres + credits via junction
   tables)
3. CloudKit starts rate-limiting due to the burst of CKRecord operations
4. Observe that throttled records are never synced

Console output:
"
Caught error: <CKError 0x10b6fccc0: "Service Unavailable" (6/2009); Retry after 13.0 seconds; container ID = container_id>: SQLiteData CloudKit Failure

SQLiteData (private.db) willFetchRecordZoneChanges
✅ Zone: co.pointfree.SQLiteData.defaultZone:defaultOwner
❌ requestRateLimited

error fetching changes for context :
<CKError 0x1313b4330: "Request Rate Limited" (7/2062);
"Operation throttled by previous server http 429 reply. Retry after 11.0 seconds.">;
"

Checklist

• I have determined whether this bug is also reproducible in a vanilla SwiftUI project.
• I have determined whether this bug is also reproducible in a vanilla GRDB project.
• If possible, I've reproduced the issue using the main branch of this package.
• This issue hasn't been addressed in an existing GitHub issue or discussion.

Expected behavior

Transient errors (at minimum .serviceUnavailable, .requestRateLimited, .zoneBusy, .networkFailure, .networkUnavailable) should re-queue the failed record so CKSyncEngine can retry it, similar to how .batchRequestFailed is handled:

  case .serviceUnavailable, .requestRateLimited, .zoneBusy,
       .networkFailure, .networkUnavailable:                                                                               
    newPendingRecordZoneChanges.append(.saveRecord(failedRecord.recordID))

Actual behavior

The continue skips the record without appending it to newPendingRecordZoneChanges. Since the defer block only adds records in that array back to syncEngine.state, the dropped records are permanently lost from the sync queue.

Reproducing project

In apps with many related tables, a single save operation (e.g., movie + 5 genres + 10 credits = 16 records) easily triggers CloudKit rate limiting. Once throttling begins, it cascades — more records get dropped, more retries fail, and data never syncs. Calling syncEngine.syncChanges() doesn't help because the records are no longer tracked as pending.

SQLiteData version information

1.6.1 (da3a94e)

Sharing version information

2.7.4

GRDB version information

7.10.0

Destination operating system

iOS 26

Xcode version information

26.4

Swift Compiler version information

Swift 6

[mbrandonw]

Hi @mario-luis-dev, thanks for the report, but are you 100% that the data is actually lost? According to the docs on CKSyncEngine, which is what SyncEngine uses under the hood, it automatically handles requestRateLimited and serviceUnavailable (and other errors):

https://developer.apple.com/documentation/cloudkit/cksyncengine-5sie5#Error-Handling

Error Handling
There are some transient errors that the sync engine handles automatically behind the scenes. The sync engine retries the operations for these transient errors automatically when it makes sense to do so. Specifically, the sync engine will handle the following errors on your behalf:

• CKError.Code.notAuthenticated
• CKError.Code.accountTemporarilyUnavailable
• CKError.Code.networkFailure
• CKError.Code.networkUnavailable
• CKError.Code.requestRateLimited
• CKError.Code.serviceUnavailable
• CKError.Code.zoneBusy

When the sync engine encounters one of these errors, it waits for the system to be in a good state, and tries again. For example, if the server sends back a CKError.Code.requestRateLimited error, the sync engine respects this throttle and tries again after the error’s retry-after time.

In fact, it's part of CKSyncEngine's design that you can enqueue hundreds or thousands of changes to it, and then it is responsible for batching them and sending to iCloud. That's what the nextRecordZoneChangeBatch(_:syncEngine:) delegate method is all about, and we implement that method to prepare the batches.

Further, even Apple's sample code for CKSyncEngine specifically calls out those errors as not needing to be handled.

[mbrandonw]

Is there a chance the problem you are seeing is related to this? If so, it's unfortunately an Apple bug that will hopefully be fixed soon and not require a new iOS update.

[mario-luis-dev]

Hey Brandon, thanks so much for the prompt responses; very much appreciated.

I'm going through the docs (and through your CloudKit video series) to make sure I'm not missing something, but I can tell you that right now it's all a giant mess.

After further debugging, what I'm noticing is that even though records are not completely disappearing, they're taking very long to sync (I'm talking "leave the phone on with Auto Lock set to Never for half an hour" before I see records synced). And even then, some records won't appear at all until I manually restart the engine or trigger it with another action.

This is all happening in both debug and production; the app is live on the App Store, it's called "Cinephile". I'll DM you on X some Premium codes (it's the least I could do in any case to thank you for your work) so you can try it and see for yourself. Saving a movie also saves the entire cast + producer and director + genres, etc; it's even worse for TV shows because seasons + episodes data is also persisted. This is all handled quite nicely by SQLiteData locally, but the sync is utterly broken.

[mbrandonw]

This does indeed sound like the issue I linked to above, and so we will have to wait for Apple to fix it. Seems like a pretty big issue so hopefully it’s top priority.