Imported from pradeepmouli/swift-template (.agents/skills/axiom-swiftdata-migration-diag/SKILL.md). Install upstream with npx skills add pradeepmouli/swift-template --skill axiom-swiftdata-migration-diag. Copyright stays with the author.

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 old models? → Pattern 3a (use willMigrate)
│     ├─ Forgot to save in willMigrate? → Pattern 3b (add context.save())
│     └─ Custom migration logic wrong? → Pattern 3c (debug transformation)
│
├─ Works in simulator but crashes on device?
│  └─ YES → Untested migration path
│     ├─ Never tested on real device? → Pattern 4a (real device testing)
│     ├─ Never tested upgrade path? → Pattern 4b (test v1 → v2 upgrade)
│     └─ Production data differs from test? → Pattern 4c (test with prod data)
│
└─ Relationships nil after migration?
   └─ YES → Relationship integrity broken
      ├─ Forgot to prefetch relationships? → Pattern 5a (add prefetching)
      ├─ Inverse relationship wrong? → Pattern 5b (fix inverse)
      └─ Delete rule caused cascade? → Pattern 5c (check delete rules)

Common Patterns

Pattern 1a: Fix "Expected only Arrays for Relationships"

PRINCIPLE Many-to-many relationships require explicit inverse declarations.

❌ WRONG (Causes "Expected only Arrays" error)

@Model
final class Note {
    var tags: [Tag] = []  // ❌ Missing inverse
}

@Model
final class Tag {
    var notes: [Note] = []  // ❌ Missing inverse
}

✅ CORRECT (Explicit inverse)

@Model
final class Note {
    @Relationship(deleteRule: .nullify, inverse: \Tag.notes)
    var tags: [Tag] = []  // ✅ Inverse specified
}

@Model
final class Tag {
    @Relationship(deleteRule: .nullify, inverse: \Note.tags)
    var notes: [Note] = []  // ✅ Inverse specified
}

Why this works SwiftData requires explicit inverse for many-to-many to create junction table correctly.

Time cost 2 minutes to add inverse declarations

Pattern 1b: iOS 17.0 Alphabetical Bug Workaround

PRINCIPLE In iOS 17.0, many-to-many relationships could fail if model names were in alphabetical order.

❌ WRONG (Crashes in iOS 17.0)

@Model
final class Actor {
    @Relationship(deleteRule: .nullify, inverse: \Movie.actors)
    var movies: [Movie]  // ❌ No default value
}

@Model
final class Movie {
    @Relationship(deleteRule: .nullify, inverse: \Actor.movies)
    var actors: [Actor]  // ❌ No default value
}
// Crashes if "Actor" < "Movie" alphabetically

✅ CORRECT (Works in iOS 17.0+)

@Model
final class Actor {
    @Relationship(deleteRule: .nullify, inverse: \Movie.actors)
    var movies: [Movie] = []  // ✅ Default value
}

@Model
final class Movie {
    @Relationship(deleteRule: .nullify, inverse: \Actor.movies)
    var actors: [Actor] = []  // ✅ Default value
}

Fixed in iOS 17.1+

Time cost 1 minute to add default values

Pattern 2a: Schema Version Mismatch

PRINCIPLE Migration plan's schemas array must include ALL versions in order.

❌ WRONG (Missing version causes crash)

enum MigrationPlan: SchemaMigrationPlan {
    static var schemas: [any VersionedSchema.Type] {
        [SchemaV1.self, SchemaV3.self]  // ❌ Missing V2!
    }

    static var stages: [MigrationStage] {
        [migrateV1toV2, migrateV2toV3]  // References V2 but not in schemas
    }
}

✅ CORRECT (All versions in order)

enum MigrationPlan: SchemaMigrationPlan {
    static var schemas: [any VersionedSchema.Type] {
        [SchemaV1.self, SchemaV2.self, SchemaV3.self]  // ✅ All versions
    }

    static var stages: [MigrationStage] {
        [migrateV1toV2, migrateV2toV3]
    }
}

Time cost 2 minutes to add missing version

Pattern 3a: Data Loss from willMigrate/didMigrate Misuse

PRINCIPLE Old models only accessible in willMigrate, new models only in didMigrate.

❌ WRONG (Tries to access old models in didMigrate)

static let migrate = MigrationStage.custom(
    fromVersion: SchemaV1.self,
    toVersion: SchemaV2.self,
    willMigrate: nil,
    didMigrate: { context in
        // ❌ CRASH: SchemaV1.Note doesn't exist here
        let oldNotes = try context.fetch(FetchDescriptor<SchemaV1.Note>())

        // Data lost because transformation never ran
    }
)

✅ CORRECT (Transform in willMigrate)

static let migrate = MigrationStage.custom(
    fromVersion: SchemaV1.self,
    toVersion: SchemaV2.self,
    willMigrate: { context in
        // ✅ SchemaV1.Note exists here
        let oldNotes = try context.fetch(FetchDescriptor<SchemaV1.Note>())

        // Transform data while old models still accessible
        for note in oldNotes {
            note.transformed = transformLogic(note.oldValue)
        }

        try context.save()  // ✅ Save before migration completes
    },
    didMigrate: nil
)

Time cost 5 minutes to move logic to correct closure

Pattern 4a: Real Device Testing

PRINCIPLE Simulator deletes database on rebuild. Real devices keep persistent databases.

Testing Workflow

# 1. Install v1 on real device
# Build with SchemaV1 as current version
# Run app, create sample data (100+ records)

# 2. Verify data exists
# Check app: should see 100+ records

# 3. Install v2 with migration
# Build with SchemaV2 as current version + migration plan
# Install over existing app (don't delete)

# 4. Verify migration succeeded
# App launches without crash
# Data still exists (100+ records)
# Relationships intact

Migration Test Code

import Testing
import SwiftData

@Test func testMigrationOnRealDevice() throws {
    // This test MUST run on real device, not simulator
    #if targetEnvironment(simulator)
    throw XCTSkip("Migration test requires real device")
    #endif

    let container = try ModelContainer(
        for: Schema(versionedSchema: SchemaV2.self),
        migrationPlan: MigrationPlan.self
    )

    let context = container.mainContext
    let notes = try context.fetch(FetchDescriptor<SchemaV2.Note>())

    // Verify data preserved
    #expect(notes.count > 0)

    // Verify relationships
    for note in notes {
        if note.folder != nil {
            #expect(note.folder?.notes.contains { $0.id == note.id } == true)
        }
    }
}

Time cost 15 minutes to test on real device

Pattern 5a: Relationship Prefetching to Preserve Integrity

PRINCIPLE Fetch relationships eagerly during migration to avoid faulting errors.

❌ WRONG (Relationships may fault and break)

static let migrate = MigrationStage.custom(
    fromVersion: SchemaV1.self,
    toVersion: SchemaV2.self,
    willMigrate: { context in
        let notes = try context.fetch(FetchDescriptor<SchemaV1.Note>())

        for note in notes {
            // ❌ May trigger fault, relationship not loaded
            let folderName = note.folder?.name
        }
    },
    didMigrate: nil
)

✅ CORRECT (Prefetch relationships)

static let migrate = MigrationStage.custom(
    fromVersion: SchemaV1.self,
    toVersion: SchemaV2.self,
    willMigrate: { context in
        var fetchDesc = FetchDescriptor<SchemaV1.Note>()

        // ✅ Prefetch relationships
        fetchDesc.relationshipKeyPathsForPrefetching = [\.folder, \.tags]

        let notes = try context.fetch(fetchDesc)

        for note in notes {
            // ✅ Relationships already loaded
            let folderName = note.folder?.name
            let tagCount = note.tags.count
        }

        try context.save()
    },
    didMigrate: nil
)

Time cost 3 minutes to add prefetching

Quick Reference: Error → Fix Mapping

Debugging Checklist

When migration fails, verify ALL of these:

• All models included in VersionedSchema.models array
• All schema versions included in SchemaMigrationPlan.schemas array
• Migration stages match schema transitions (V1→V2, V2→V3)
• Many-to-many relationships have explicit inverse: on both sides
• Container initialized with correct latest schema version
• Migration plan registered in ModelContainer initialization
• Tested on real device (not just simulator)
• Tested upgrade path (v1 → v2), not just fresh install
• SwiftData debug logging enabled (-com.apple.coredata.swiftdata.debug 1)
• Data transformation logic in willMigrate (not didMigrate)

When You're Stuck After 30 Minutes

If you've spent >30 minutes and the migration issue persists:

STOP. You either

1. Skipped mandatory diagnostics (most common)
2. Misidentified the actual problem
3. Applied wrong pattern for your symptom
4. Haven't tested on real device/real data
5. Have complex edge case requiring two-stage migration

MANDATORY checklist before claiming "skill didn't work"

• I ran all Mandatory First Steps diagnostics
• I identified the problem type (relationship, schema mismatch, data loss, testing gap)
• I enabled SwiftData debug logging and examined SQL output
• I tested on real device with real data (not simulator)
• I applied the FIRST matching pattern from Decision Tree
• I verified all models included in VersionedSchema
• I checked relationship inverse declarations

If ALL boxes are checked and still broken

• You need two-stage migration (covered in axiom-swiftdata-migration skill)
• Time cost: 30-60 minutes for complex type change migration
• Ask: "What data transformation is actually needed?" and implement two-stage pattern

Time Cost Transparency

• Pattern 1 (relationship inverse): 2-3 minutes
• Pattern 2 (schema version): 2-5 minutes
• Pattern 3 (willMigrate fix): 5-10 minutes
• Pattern 4 (real device testing): 15-30 minutes
• Pattern 5 (relationship prefetching): 3-5 minutes

Real-World Impact

Before SwiftData migration debugging 2-8 hours per issue

• App crashes on launch in production
• Data loss for existing users
• Relationships broken after migration
• Simulator success, device failure
• Customer trust damaged

After 15-45 minutes with systematic diagnosis

• Identify problem type with diagnostics (5 min)
• Apply correct pattern (5-10 min)
• Test on real device (15-30 min)
• Deploy with confidence

Key insight SwiftData has well-established patterns for every common migration issue. The problem is developers don't know which diagnostic applies to their error.

Resources

WWDC: 2025-291, 2023-10195

Docs: /swiftdata

Skills: axiom-swiftdata-migration, axiom-swiftdata, axiom-database-migration

Created 2025-12-09 Status Production-ready diagnostic patterns Framework SwiftData (Apple) Swift 5.9+