How to Fix iOS Core Data Migration Error

In this tutorial, you'll learn about How to Fix iOS Core Data Migration Error. We cover key concepts, practical examples, and best practices.

The Problem

Your app crashes after updating the Core Data model:

The model used to open the store is incompatible with the one
used to create the store

Or:

Can't find model for source store

The persistent store was created with a different data model version than the current one.

Quick Fix

Step 1: Enable lightweight migration

In NSPersistentContainer or NSPersistentStoreCoordinator:

let container = NSPersistentContainer(name: "DataModel")
container.persistentStoreDescriptions.first?.shouldMigrateStoreAutomatically = true
container.persistentStoreDescriptions.first?.shouldInferMappingModelAutomatically = true

These two flags enable automatic lightweight migration for simple changes (add attribute, add relationship, etc.).

Step 2: Create a new model version

1. Select the .xcdatamodeld file
2. Editor > Add Model Version
3. Name it (e.g., "DataModel 2")
4. Make changes to the new version
5. Set it as the current version: select the .xcdatamodeld file, open the File Inspector, select the new version under Model Version

Step 3: Add the new version to the code

// In your Core Data stack setup
let modelURL = Bundle.main.url(forResource: "DataModel", withExtension: "momd")!
let model = NSManagedObjectModel(contentsOf: modelURL)!

The app automatically loads the current model version.

Step 4: Check what lightweight migration supports

Lightweight migration supports:

• Adding/removing attributes
• Making optional/non-optional
• Renaming with renamingIdentifier
• Adding/removing relationships

It does NOT support:

• Combining relationships
• Merging entities
• Complex data transformations

Step 5: Create a mapping model for heavy migrations

File > New > File > Mapping Model > Select source and destination versions.

Then implement NSEntityMigrationPolicy subclass:

class UserMigrationPolicy: NSEntityMigrationPolicy {
    override func createDestinationInstances(
        forSource sInstance: NSManagedObject,
        in mapping: NSEntityMapping,
        manager: NSMigrationManager
    ) throws {
        // Custom transformation logic
    }
}

Step 6: Reset the simulator for testing

xcrun simctl erase all

This deletes all apps and their Core Data stores. Always test migration from actual version N to N+1 using a device with real data.

Step 7: Delete and reinstall (development only)

If you do not care about existing data during development, use:

container.persistentStoreDescriptions.first?.shouldMigrateStoreAutomatically = false
// Delete the store file manually
try FileManager.default.removeItem(at: storeURL)

Prevention

• Enable automatic migration in the Core Data stack from the start.
• Version your model before making any schema changes.
• Test migrations with a copy of a production database.

Common Mistakes with core data migration

1. Using return to exit a function early instead of wrapping a pure value in the monad
2. Mixing let bindings with <- bindings in do notation, producing type errors
3. Overlapping type class instances that cause GHC to reject the program with ambiguous dispatch errors

These mistakes appear frequently in real-world IOS code. DodaTech's contributors have identified these patterns through analysis of open-source projects and production systems.

Practice Exercise

Write a pure function that safely divides two integers using Maybe, then test it with edge cases like division by zero and negative numbers.

This exercise reinforces the concepts covered in this guide. Try implementing it before checking online solutions.

FAQ

DodaTech Tool Reference

Doda Browser's File Manager can browse the app's Documents folder on a device to inspect Core Data SQLite files, verifying migration success or failure.