SwiftData Migration Diagnostics

Overview

SwiftData migration failures manifest as production crashes, data loss, corrupted relationships, or simulator-only success. Core principle 90% of migration failures stem from missing models in VersionedSchema, relationship inverse issues, or untested migration paths—not SwiftData bugs.

Red Flags — Suspect SwiftData Migration Issue

If you see ANY of these, suspect a migration configuration problem:

• App crashes on launch after schema change
• "Expected only Arrays for Relationships" error
• "The model used to open the store is incompatible with the one used to create the store"
• "Failed to fulfill faulting for [relationship]"
• Migration works in simulator but crashes on real device
• Data exists before migration, gone after
• Relationships broken after migration (nil where they shouldn't be)
• ❌ FORBIDDEN "SwiftData migrations are broken, we should use Core Data"
  • SwiftData handles millions of migrations in production apps
  • Schema mismatches and relationship errors are always configuration, 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:
//   - "Expected only Arrays" = relationship inverse missing
//   - "incompatible model" = schema version mismatch
//   - "Failed to fulfill faulting" = relationship integrity broken
//   - Simulator works, device crashes = untested migration path
// Record: "Error type: [exact message]"

// 2. Check schema version configuration
// In your migration plan:
enum MigrationPlan: SchemaMigrationPlan {
    static var schemas: [any VersionedSchema.Type] {
        // ✅ VERIFY: All versions in order?
        // ✅ VERIFY: Latest version matches container?
        [SchemaV1.self, SchemaV2.self, SchemaV3.self]
    }

    static var stages: [MigrationStage] {
        // ✅ VERIFY: Migration stages match schema transitions?
        [migrateV1toV2, migrateV2toV3]
    }
}

// In your app:
let schema = Schema(versionedSchema: SchemaV3.self)  // ✅ VERIFY: Matches latest in plan?
let container = try ModelContainer(
    for: schema,
    migrationPlan: MigrationPlan.self  // ✅ VERIFY: Plan is registered?
)
// Record: "Schema version: latest is [version]"

// 3. Check all models included in VersionedSchema
enum SchemaV2: VersionedSchema {
    static var models: [any PersistentModel.Type] {
        // ✅ VERIFY: Are ALL models listed? (even unchanged ones)
        [Note.self, Folder.self, Tag.self]
    }
}
// Record: "Missing models? Yes/no"

// 4. Check relationship inverse declarations
@Model
final class Note {
    @Relationship(deleteRule: .nullify, inverse: \Folder.notes)  // ✅ VERIFY: inverse specified?
    var folder: Folder?

    @Relationship(deleteRule: .nullify, inverse: \Tag.notes)  // ✅ VERIFY: inverse specified?
    var tags: [Tag] = []
}
// Record: "Relationship inverses: all specified? Yes/no"

// 5. Enable SwiftData debug logging
// In Xcode scheme, add argument:
// -com.apple.coredata.swiftdata.debug 1
// Run and check Console for SQL queries
// Record: "Debug log shows: [what you see]"

What this tells you

• "Expected only Arrays for Relationships" → Proceed to Pattern 1 (relationship inverse fix)
• "incompatible model" → Proceed to Pattern 2 (schema version mismatch)
• Missing models in VersionedSchema → Proceed to Pattern 3 (complete schema snapshot)
• Simulator works, device crashes → Proceed to Pattern 4 (migration testing)
• Data lost after migration → Proceed to Pattern 5 (willMigrate/didMigrate misuse)

MANDATORY INTERPRETATION

Before changing ANY code, identify ONE of these:

1. If error is "Expected only Arrays" AND relationship inverse missing → Relationship configuration issue
2. If error mentions "incompatible" AND schema versions don't match → Version mismatch
3. If models are missing from VersionedSchema → Incomplete schema snapshot
4. If simulator succeeds but device fails → Untested migration path
5. If data exists before but not after → willMigrate/didMigrate limitation violated

If diagnostics are contradictory or unclear

• STOP. Do NOT proceed to patterns yet
• Add -com.apple.coredata.swiftdata.debug 1 and examine SQL output
• Check file system: does .sqlite file exist? What size?
• Establish baseline: what's actually happening vs. what you assumed

Verifying Migration Completed Successfully

Use this section when migration appears to complete without errors, but you want to verify data integrity.

Quick Verification Checklist

After migration runs without crashing:

// 1. Verify record count matches pre-migration
let context = container.mainContext
let postMigrationCount = try context.fetch(FetchDescriptor<Note>()).count
print("Post-migration count: \(postMigrationCount)")
// Compare to pre-migration count

// 2. Spot-check specific records
let sampleNote = try context.fetch(
    FetchDescriptor<Note>(predicate: #Predicate { $0.id == "known-test-id" })
).first
print("Sample note title: \(sampleNote?.title ?? "MISSING")")

// 3. Verify relationships intact
if let note = sampleNote {
    print("Folder relationship: \(note.folder != nil ? "✓" : "✗")")
    print("Tags count: \(note.tags.count)")

    // Verify inverse relationships
    if let folder = note.folder {
        let folderHasNote = folder.notes.contains { $0.id == note.id }
        print("Inverse relationship: \(folderHasNote ? "✓" : "✗")")
    }
}

// 4. Check for orphaned data
let orphanedNotes = try context.fetch(
    FetchDescriptor<Note>(predicate: #Predicate { $0.folder == nil })
)
print("Orphaned notes (should be 0 if cascade delete worked): \(orphanedNotes.count)")

What Successful Migration Looks Like

Console Output:

Post-migration count: 1523  // Matches pre-migration
Sample note title: Test Note  // Not "MISSING"
Folder relationship: ✓
Tags count: 3
Inverse relationship: ✓
Orphaned notes: 0

If you see:

• Record count differs → Data loss (check willMigrate logic)
• "MISSING" records → Schema mismatch or fetch error
• Relationships nil → Inverse configuration or prefetching issue
• Orphaned records >0 → Cascade delete rule not working

See patterns below for specific fixes.

Decision Tree

SwiftData migration problem suspected?
├─ Error: "Expected only Arrays for Relationships"?
│  └─ YES → Relationship inverse missing
│     ├─ Many-to-many relationship? → Pattern 1a (explicit inverse)
│     ├─ One-to-many relationship? → Pattern 1b (verify both sides)
│     └─ iOS 17.0 alphabetical bug? → Pattern 1c (default value workaround)
│
├─ Error: "incompatible model" or crash on launch?
│  └─ YES → Schema version mismatch
│     ├─ Latest schema not in plan? → Pattern 2a (add to schemas array)
│     ├─ Migration stage missing? → Pattern 2b (add stage)
│     └─ Container using wrong schema? → Pattern 2c (verify version)
│
├─ Migration runs but data missing?
│  └─ YES → Data loss during migration
│     ├─ Used didMigrate to access o