Troubleshooting

Common CloudKit sync issues and solutions for TheCompanyApp.

Not Syncing Across Devices

Symptom

Created company on iPhone, doesn't appear on iPad (same Apple ID).

Causes & Solutions

1. Not Signed In to iCloud

Settings → [Your Name] → iCloud → Ensure signed in

2. iCloud Drive Disabled for App

Settings → [Your Name] → iCloud → TheCompanyApp → Enable toggle

3. Network Issues

• Check Wi-Fi or cellular connection

• Try toggling Airplane Mode off/on

• Wait 1-2 minutes for sync to complete

4. CloudKit Zone Not Created

• Delete app, reinstall

• Sign out of iCloud, sign back in

• Reset sync: See "Reset CloudKit Data" below

5. Check Sync Events Add logging to detect sync failures:

NotificationCenter.default.addObserver(forName: NSPersistentCloudKitContainer.eventChangedNotification) { notification in
    if let event = notification.userInfo?[NSPersistentCloudKitContainer.eventNotificationUserInfoKey] as? NSPersistentCloudKitContainer.Event {
        print("CloudKit Event: \(event.type), Success: \(event.succeeded)")
        if let error = event.error {
            print("Sync Error: \(error)")
        }
    }
}

Share Not Received

Symptom

Owner sends share link, participant taps link but nothing happens.

Solutions

1. Check URL Scheme

• Share URL must start with https://www.icloud.com/share/

• Ensure universal links enabled in Xcode

2. App Not Installed

• Participant must have TheCompanyApp installed

• Safari won't redirect to app otherwise

3. Wrong Apple ID

• Participant must be signed in to iCloud

• Cannot accept share without iCloud account

4. Share Already Accepted

• Check if company already in "Shared With Me" section

• Company might have synced but UI not refreshed

5. Manual Accept Try programmatic accept:

let container = CKContainer(identifier: "iCloud.TheCompany.3N")
let metadata = try await container.shareMetadata(for: shareURL)
_ = try await container.accept(metadata)

Duplicate Companies

Symptom

Same company appears multiple times in list.

Causes

1. Accepted Share Multiple Times

• Each acceptance creates new local record

• CloudKit de-duplicates on server, local doesn't

2. Local and Shared Copies

• Owner sees company in Private Store

• After sharing, it appears in Shared Store duplicate? No - should only be in Private.

• Participant sees only in Shared Store

Solution

Delete one copy:

let duplicates = companies.filter { $0.companyID == targetID }
if duplicates.count > 1 {
    // Keep the one in correct store
    for dup in duplicates where dup.objectID.persistentStore != correctStore {
        viewContext.delete(dup)
    }
    try viewContext.save()
}

Participant Can't Edit

Symptom

Participant sees data but cannot modify.

Solutions

1. Check CKShare Permission Owner must set "Can Edit":

share.publicPermission = .readWrite
try await container.save(share)

2. Check AccessControl Query AccessControl entity:

let access = fetchAccessControl(company: company.companyID, user: participantName)
print("Can edit inventory: \(access?.canEditInventory)")

3. Network Delay

• Wait 30 seconds after accepting share

• Permissions sync may be delayed

Changes Not Syncing to Owner

Symptom

Participant creates order, owner doesn't see it.

Solutions

1. Enlistment Missing Ensure new objects enlisted in share:

func saveOrderToSharedCompany(_ order: Orders, company: Companies) async {
    try viewContext.save()
    
    // Enlist in share
    let shares = try? await container.fetchShares(matching: [company.objectID])
    if let share = shares?[company.objectID] {
        _ = try? await container.share([order], to: share)
    }
}

2. Owner Polling Shared Database Owner's device must poll both Private and Shared:

• This is automatic with NSPersistentCloudKitContainer

• Restart app to force refresh

3. Merge Policy Conflict Check if local changes being overwritten:

viewContext.mergePolicy = NSMergeByPropertyObjectTrumpMergePolicy

Quota Exceeded

Symptom

Error: "iCloud storage full" or CKErrorQuotaExceeded.

Solutions

1. Public vs Private Database

• TheCompanyApp uses Private/Shared (counts against user's iCloud quota)

• Public Database has 10 PB free (not used here)

2. User's iCloud Storage Full

Settings → [Your Name] → iCloud → Manage Storage

User must upgrade plan or delete files.

3. Large Attachments

• Reduce image sizes (see ImageOptimizer.swift)

• Delete old dispatch records

• Archive completed orders

4. Developer Account Exceeded

• App owner's CloudKit dashboard shows usage

• Contact Apple if limits reached

Network Errors

CKErrorNetworkUnavailable

Solution: Check internet connection, wait and retry.

CKErrorZoneBusy

Solution: CloudKit throttling. Wait 30-60 seconds, retry.

CKErrorRequestRateLimited

Solution: Too many requests. Implement exponential backoff:

func retryWithBackoff(attempt: Int = 0) async {
    let delay = min(pow(2.0, Double(attempt)), 60.0)
    try? await Task.sleep(nanoseconds: UInt64(delay * 1_000_000_000))
    // Retry operation
}

Reset CloudKit Data

Warning: Deletes all CloudKit data. Use only for testing.

Development Environment

1. Open CloudKit Dashboard: https://icloud.developer.apple.com/dashboard

2. Select TheCompanyApp container

3. Development → Reset Schema and Records

4. Delete app from device, reinstall

Production Environment

Cannot reset production data. Users must:

• Delete all companies manually

• Or delete app, reinstall (local data only)

Enable CloudKit Logging

macOS/iOS Console App:

1. Connect device to Mac

2. Open Console.app

3. Filter by com.apple.coredata.cloudkit

4. Reproduce issue

5. Look for CloudKit operation logs

Xcode Arguments:

Edit Scheme → Run → Arguments → Arguments Passed On Launch:
-com.apple.CoreData.CloudKitDebug 3
-com.apple.CoreData.Logging.oslog 1

Logs will appear in Xcode console during sync operations.

---

Related: Sync States, Conflict Resolution, Share Testing Checklist