# CloudKit Sync - Troubleshooting & Debugging

## Debugging Checklist

### 1. Verify CloudKit Account Status

```swift

// In AppDelegate

private func logCloudKitStatus() {

    let container = CKContainer(identifier: "iCloud.ro.xdev.USB-Meter")

    container.accountStatus { status, error in

        if let error {

            print("CloudKit error: \(error.localizedDescription)")

            return

        }

        switch status {

        case .available:

            print("✅ CloudKit available")

        case .noAccount:

            print("❌ No iCloud account")

        case .restricted:

            print("❌ CloudKit restricted (parental controls?)")

        case .couldNotDetermine:

            print("❌ Status unknown")

        case .temporarilyUnavailable:

            print("⚠️ CloudKit temporarily unavailable")

        @unknown default:

            print("⚠️ Unknown status")

        }

    }

}

```

**Expected:** `.available` or changes won't sync

---

### 2. Check Entitlements

Verify `USB Meter.entitlements` has:

```xml

<key>com.apple.developer.icloud-container-identifiers</key>

<array>

    <string>iCloud.ro.xdev.USB-Meter</string>

</array>

<key>com.apple.developer.icloud-services</key>

<array>

    <string>CloudKit</string>

</array>

<key>com.apple.developer.ubiquity-container-identifiers</key>

<array>

    <string>iCloud.ro.xdev.USB-Meter</string>

</array>

```

If missing:

- ❌ App can't access CloudKit

- ❌ No sync errors in logs (silent failure)

---

### 3. Monitor Sync Logs

Enable enhanced Core Data debugging:

**In Xcode scheme editor:**

1. Select scheme → Edit Scheme → Run → Arguments

2. Add Launch Arguments:

   ```

   -com.apple.CoreData.SQLDebug 1

   -com.apple.CoreData.ConcurrencyDebug 1

   ```

**In terminal:**

```bash

# Follow app logs

log stream --predicate 'process == "USB Meter"' --level debug

```

**Look for:**

- `NSPersistentCloudKitContainer` initialization messages

- `cloudkit:` messages (sync operations)

- `CoreData:` messages (database operations)

---

### 4. Check Persistent Store Description

```swift

// In AppDelegate.persistentContainer

if let description = container.persistentStoreDescriptions.first {

    print("Store URL: \(description.url?.path ?? "nil")")

    print("Options: \(description.options ?? [:])")

    print("CloudKit container: \(description.cloudKitContainerOptions?.containerIdentifier ?? "nil")")

}

```

**Expected:**

- URL should point to `.../Library/Application Support/CKModel.sqlite`

- CloudKit container identifier must match entitlements

---

### 5. Verify Remote Notifications Are Set Up

```swift

// In AppData

private func setupRemoteChangeNotificationObserver() {

    NotificationCenter.default.addObserver(

        self,

        selector: #selector(remoteStoreDidChange),

        name: .NSPersistentStoreRemoteChange,

        object: nil

    )

    print("✅ Remote change observer registered")

}

@objc private func remoteStoreDidChange() {

    print("🔄 Remote CloudKit change received")

    DispatchQueue.main.async {

        self.reloadSettingsFromCloudStore()

    }

}

```

**Problem:** If `reloadSettingsFromCloudStore` is never called, check if observer is registered

---

## Common Issues & Fixes

### Issue 1: "Changes not syncing to other devices"

**Diagnosis:**

```swift

// Check if save succeeded

do {

    try appData.persistentContainer.viewContext.save()

    print("✅ Save successful")

} catch {

    print("❌ Save failed: \(error)")

}

// Check if DeviceSettings record exists

let request = NSFetchRequest<NSFetchRequestExpression>(entityName: "DeviceSettings")

let count = try? appData.persistentContainer.viewContext.count(for: request)

print("Records in store: \(count ?? 0)")

```

**Fixes:**

1. **Check Account Status** → must be `.available`

2. **Check Merge Policy** → ensure `NSMergeByPropertyStoreTrumpMergePolicy`

3. **Check Observer** → `remoteStoreDidChange` registered?

4. **Force Sync:**

   ```swift

   appData.persistentContainer.viewContext.refreshAllObjects()

   appData.reloadSettingsFromCloudStore()

   ```

### Issue 2: "Duplicates appearing in CloudKit"

**Diagnosis:**

```swift

// Check for MAC address duplicates

let request = NSFetchRequest<NSDictionary>(entityName: "DeviceSettings")

request.returnsDistinctResults = true

request.returnsObjectsAsFaults = false

request.resultType = .dictionaryResultType

request.returnsDistinctResults = true

let macs = try? appData.persistentContainer.viewContext.fetch(request)

    .compactMap { $0["macAddress"] as? String }

let duplicates = macs?.filter { mac in

    macs?.filter { $0 == mac }.count ?? 0 > 1

}

print("Duplicate MACs: \(duplicates ?? [])")

```

**Fixes:**

1. **Rebuild v3:** Ensure `cloudStoreRebuildVersion = 3` is deployed

2. **Check `rebuildCanonicalStoreIfNeeded`:**

   ```swift

   // Manually trigger

   appData.cloudStore?.rebuildCanonicalStoreIfNeeded(version: 3)

   ```

3. **Verify UserDefaults:**

   ```swift

   let rebuilt = UserDefaults.standard.bool(forKey: "cloudStoreRebuildVersion.3")

   print("Rebuild v3 completed: \(rebuilt)")

   ```

### Issue 3: "Connection status stuck as 'Connected on Device X'"

**Diagnosis:**

```swift

// Check connection record

let request = NSFetchRequest<NSManagedObject>(entityName: "DeviceSettings")

let records = try? appData.persistentContainer.viewContext.fetch(request)

for record in records ?? [] {

    if let expiry = record.value(forKey: "connectedExpiryAt") as? Date {

        let isExpired = expiry < Date.now

        print("✋ MAC \(record.value(forKey: "macAddress") ?? "?") expires at \(expiry), expired: \(isExpired)")

    }

}

```

**Fixes:**

1. **Manually clear lock:**

   ```swift

   appData.clearMeterConnection(macAddress: "aa:bb:cc:dd:ee:ff")

   ```

2. **Check TTL hardcode:** Should be 120s in `setConnection()`

3. **Verify system clock** on Device A (didn't fall asleep or drift)

### Issue 4: "Core Data save errors" with `NSError 1569`

**Symptom:**

```

NSError Domain=NSCocoaErrorDomain Code=1569

"The object's persistent store is not reachable"

```

**Causes:**

1. ❌ Old model with `uniquenessConstraint` conflicting with CloudKit

2. ❌ All attributes on DeviceSettings aren't `optional="YES"`

**Fixes:**

1. **Verify model v2+:** Check `.xccurrentversion` points to `USB_Meter 2.xcdatamodel`

2. **Check attributes:** All must be `optional="YES"` (inspect `.xcdatamodel/contents`)

3. **Reset store if persists:**

   ```swift

   // Delete local store to force rebuild from CloudKit

   let storeURL = appData.persistentContainer.persistentStoreDescriptions.first?.url

   let fileManager = FileManager.default

   try? fileManager.removeItem(at: storeURL)

   ```

---

## Monitoring CloudKit Sync in Real Time

### Dashboard View (for debugging)

```swift

struct CloudKitDebugView: View {

    @ObservedObject var appData: AppData

    var body: some View {

        VStack(alignment: .leading, spacing: 8) {

            Text("CloudKit Sync Status")

                .font(.headline)

            DebugItem(label: "Account", value: appData.cloudKitAccountStatus)

            DebugItem(label: "Device ID", value: UIDevice.current.identifierForVendor?.uuidString ?? "?")

            DebugItem(label: "Records", value: "\(appData.deviceSettingsCount)")

            DebugItem(label: "Pending", value: "\(appData.pendingSyncCount)")

            Button("Force Reload") {

                appData.reloadSettingsFromCloudStore()

            }

        }

        .padding()

        .font(.caption)

    }

}

struct DebugItem: View {

    let label: String

    let value: String

    var body: some View {

        HStack {

            Text(label).font(.caption2).foregroundColor(.secondary)

            Spacer()

            Text(value).font(.caption).monospaced()

        }

    }

}

```

---

## Network Conditions Testing

### Simulate CloudKit Unavailability

1. Xcode → Debug → Simulate Location → [Custom]

2. Instrument → Network Link Conditioner → "Very Bad Network"

### Expected Behavior:

- ✅ Local changes proceed (saved to local DB)

- ✅ Notification badge appears: "📶 Waiting for sync…"

- ✅ When network returns → auto-resumes sync

---

## CloudKit Container Inspection (Advanced)

Using CloudKit Console (requires Apple developer account):

1. Go to https://icloud.developer.apple.com/cloudkit

2. Select container: `iCloud.ro.xdev.USB-Meter`

3. Browse `DeviceSettings` records:

   - Check for duplicates by `macAddress`

   - Verify `connectedByDeviceID` matches expected device UUIDs

   - Check `updatedAt` timestamps

---

## Performance Profiling

```swift

// Measure reloadSettingsFromCloudStore() performance

let start = Date()

appData.reloadSettingsFromCloudStore()

let duration = Date().timeIntervalSince(start)

print("Reload took \(duration * 1000)ms")  // Should be <100ms for ~10 records

```

**Benchmarks:**

| Operation | Target | Actual (good) |

|-----------|--------|---------------|

| `setConnection()` | <50ms | ~10ms |

| `reloadSettingsFromCloudStore()` | <100ms | ~30ms (5 records) |

| CloudKit push (network) | <5s | varies by connection |

| Remote notification delivery | <10s | ~2-5s (typically) |

---

## Recording Logs for Bug Reports

```bash

# Save full debug logs

log collect --start '2025-03-26 10:00:00' --output /tmp/cloudkit_logs.logarchive

# Extract readable format

log show /tmp/cloudkit_logs.logarchive \

  --predicate 'process == "USB Meter"' \

  --level debug > ~/cloudkit_debug.txt

```

Include in bug report:

1. `~/cloudkit_debug.txt`

2. Reproduction steps

3. What you expected vs. what happened

4. Device names & OS versions involved