Core Data Diagnostics & Migration

Overview

Core Data issues manifest as production crashes from schema mismatches, mysterious concurrency errors, performance degradation under load, and data corruption from unsafe migrations. Core principle 85% of Core Data problems stem from misunderstanding thread-confinement, schema migration requirements, and relationship query patterns—not Core Data defects.

Red Flags — Suspect Core Data Issue

If you see ANY of these, suspect a Core Data misunderstanding, not framework breakage:

• Crash on production launch: "Unresolvable fault" after schema change
• Thread-confinement error: "Accessing NSManagedObject on a different thread"
• App suddenly slow after adding a User→Posts relationship
• SwiftData app needs complex features; considering mixing Core Data alongside
• Schema migration works in simulator but crashes on production
• ❌ FORBIDDEN "Core Data is broken, we need a different database"
  • Core Data handles trillions of records in production apps
  • Schema mismatches and thread errors are always developer code, not framework
  • Do not rationalize away the issue—diagnose it

Critical distinction Simulator deletes the database on each rebuild, hiding schema mismatch issues. Real devices keep persistent databases and crash immediately on schema mismatch. MANDATORY: Test migrations on real device with real data before shipping.

Mandatory First Steps

ALWAYS run these FIRST (before changing code):

// 1. Identify the crash/issue type
// Screenshot the crash message and note:
//   - "Unresolvable fault" = schema mismatch
//   - "different thread" = thread-confinement
//   - Slow performance = N+1 queries or fetch size issues
//   - Data corruption = unsafe migration
// Record: "Crash type: [exact message]"

// 2. Check if it's schema mismatch
// Compare these:
let coordinator = persistentStoreCoordinator
let model = coordinator.managedObjectModel
let store = coordinator.persistentStores.first

// Get actual store schema version:
do {
    let metadata = try NSPersistentStoreCoordinator.metadataForPersistentStore(
        ofType: NSSQLiteStoreType,
        at: storeURL,
        options: nil
    )
    print("Store version identifier: \(metadata[NSStoreModelVersionIdentifiersKey] ?? "unknown")")

    // Get app's current model version:
    print("App model version: \(model.versionIdentifiers)")

    // If different = schema mismatch
} catch {
    print("Schema check error: \(error)")
}
// Record: "Store version vs. app model: match or mismatch?"

// 3. Check thread-confinement for concurrency errors
// For any NSManagedObject access:
print("Main thread? \(Thread.isMainThread)")
print("Context concurrency type: \(context.concurrencyType.rawValue)")
print("Accessing from: \(Thread.current)")
// Record: "Thread mismatch? Yes/no"

// 4. Profile relationship access for N+1 problems
// In Xcode, run with arguments:
// -com.apple.CoreData.SQLDebug 1
// Check Console for SQL queries:
//   SELECT * FROM USERS;  (1 query)
//   SELECT * FROM POSTS WHERE user_id = 1;  (1 query per user = N+1!)
// Record: "N+1 found? Yes/no, how many extra queries"

// 5. Check SwiftData vs. Core Data confusion
if #available(iOS 17.0, *) {
    // If using SwiftData @Model + Core Data simultaneously:
    // Error: "Store is locked" or "EXC_BAD_ACCESS"
    // = trying to access same database from both layers
    print("Using both SwiftData and Core Data on same store?")
}
// Record: "Mixing SwiftData + Core Data? Yes/no"

What this tells you

• Schema mismatch → Proceed to Pattern 1 (lightweight migration decision)
• Thread-confinement error → Proceed to Pattern 2 (async/await concurrency)
• N+1 queries → Proceed to Pattern 3 (relationship prefetching)
• SwiftData + Core Data conflict → Proceed to Pattern 4 (bridging)
• Slow after migration → Proceed to Pattern 5 (testing safety)

MANDATORY INTERPRETATION

Before changing ANY code, identify ONE of these:

1. If crash is "Unresolvable fault" AND store/model versions differ → Schema mismatch (not user error)
2. If crash mentions "different thread" AND you're using DispatchQueue → Thread-confinement (not thread-safe design)
3. If performance degrades with relationship access → N+1 queries (check SQL log)
4. If SwiftData and Core Data code exist together → Conflicting data layers (architectural issue)
5. If migration test passes but production fails → Edge case in real data (testing gap)

If diagnostics are contradictory or unclear

• STOP. Do NOT proceed to patterns yet
• Add print statements to every NSManagedObject access (thread check)
• Add -com.apple.CoreData.SQLDebug 1 and count SQL queries
• Establish baseline: what's actually happening vs. what you assumed

Decision Tree

Core Data problem suspected?
├─ Crash: "Unresolvable fault"?
│  └─ YES → Schema mismatch (store ≠ app model)
│     ├─ Add new required field? → Pattern 1a (lightweight migration)
│     ├─ Remove field, rename, or change type? → Pattern 1b (heavy migration)
│     └─ Don't know how to fix? → Pattern 1c (testing safety)
│
├─ Crash: "different thread"?
│  └─ YES → Thread-confinement violated
│     ├─ Using DispatchQueue for background work? → Pattern 2a (async context)
│     ├─ Mixing Core Data with async/await? → Pattern 2b (structured concurrency)
│     └─ SwiftUI @FetchRequest causing issues? → Pattern 2c (@FetchRequest safety)
│
├─ Performance: App became slow?
│  └─ YES → Likely N+1 queries
│     ├─ Accessing user.posts in loop? → Pattern 3a (prefetching)
│     ├─ Large result set? → Pattern 3b (batch sizing)
│     └─ Just added relationships? → Pattern 3c (relationship tuning)
│
├─ Using both SwiftData and Core Data?
│  └─ YES → Data layer conflict
│     ├─ Need Core Data features SwiftData lacks? → Pattern 4a (drop to Core Data)
│     ├─ Already committed to SwiftData? → Pattern 4b (stay in SwiftData)
│     └─ Unsure which to use? → Pattern 4c (decision framework)
│
└─ Migration works locally but crashes in production?
   └─ YES → Testing gap
      ├─ Didn't test with real data? → Pattern 5a (production testing)
      ├─ Schema change affects large dataset? → Pattern 5b (migration safety)
      └─ Need verification before shipping? → Pattern 5c (pre-deployment checklist)

Common Patterns

Pattern Selection Rules (MANDATORY)

Apply ONE pattern at a time, starting with diagnostics

1. Always start with Mandatory First Steps — Identify the actual problem
2. Run decision tree — Narrow to specific pattern
3. Apply ONE pattern — Don't combine patterns
4. Test on real device — Simulator hides issues
5. Verify with migration test — Before deploying

FORBIDDEN

• ❌ Changing code without diagnostics
• ❌ Skipping real device testing
• ❌ Using simulator success as proof of migration safety
• ❌ Mixing multiple migration patterns
• ❌ Deploying migrations without pre-deployment verification

Pattern 1a: Lightweight Migration (Simple Schema Changes)

PRINCIPLE Core Data can automatically migrate simple schemas (additive changes) without data loss if done correctly.

✅ SAFE Lightweight Migrations

• Adding new optional field: @NSManaged var nickname: String?
• Adding new required field WITH default: Create attribute with default value
• Renaming entity or attribute: Use mapping model with automatic mapping
• Removing unused field: Just delete from model (data stays on disk, ignored)

❌ WRONG (Crashes production)

// BAD: Adding required field without migration
@NSManaged var userID: String  // Required, no default

// BAD: Assuming simulator = production
// Works in simulator (deletes DB), crashes on real device

// BAD: Modifying field type
@NSManaged var createdAt: Date  // Was String, now Date
// Core Data can't automatically convert

✅ CORRECT (Safe lightweight migration)

// 1. In Xcode: Editor → Add Model Version
// Creates new .xcdatamodel version file

// 2. In new version, add required field WITH default:
@NSManaged var userID: String = UUID().uuidString

// 3. Mark as current model version:
// File Inspector → Versioned Core Data Model
// Check "Current Model Version"

// 4. Test:
// Simulate old version: delete app, copy old database, run with new code
// Real app loads → migration succeeded

// 5. Deploy when confident

When this works

• Adding optional fields (always safe)
• Adding required fields WITH default values
• Removing fields
• Renaming entities/attributes with mapping model

When this FAILS (don't try lightweight)

• Changing field type (String → Int)
• Making optional field required (data has nulls, can't convert)
• Complex relationship changes
• Custom data transformations needed

Time cost 5-10 minutes for lightweight migration setup

Pattern 1b: Heavy Migration (Complex Schema Changes)

PRINCIPLE When lightweight migration won't work, use NSEntityMigrationPolicy for custom transformation logic.

Use when

• Changing field types (String → Date)
• Making optional required (need to populate existing nulls)
• Complex relationship restructuring
• Custom data transformations (e.g., split "firstName lastName" into separate fields)

Example: Convert String dates to Date objects

// 1. Create mapping model
// File → New → Mapping Model
// Source: old version, Destination: new version

// 2. Create custom migration policy
class DateMigrationPolicy: NSEntityMigrationPolicy {
    override func createDestinationInstances(
        forSource sInstance: NSManagedObject,
        in mapping: NSEntityMapping,
        manager: NSMigrationManager
    ) throws {
        let destination = NSEntityDescription.insertNewObject(
            forEntityName: mapping.destinationEntityName ?? "",
            into: manager.destinationContext
        )

        for key in sInstance.entity.attributesByName.keys {
            destination.setValue(sInstance.value(forKey: key), forKey