Introduction

The error "An NSManagedObject of class 'ClassName' must have a valid NSEntityDescription" is one of the most common Core Data crashes in iOS and macOS development. It occurs when Core Data cannot find an entity description matching your managed object subclass. This typically happens due to a mismatch between the class name in code, the entity name in the .xcdatamodeld file, or the module/namespace configuration.

What Causes This Error

Core Data uses NSEntityDescription to map entity names in the data model to Swift/Objective-C classes. When you create or fetch a managed object, Core Data looks up the entity by class name. If the lookup fails, you get this crash.

The most common causes:

1. Module name mismatch — The entity's class in the data model inspector does not include the correct module prefix
2. Entity not in the data model — The entity was deleted or renamed in .xcdatamodeld but the class still exists
3. Wrong managed object context — Using a context whose persistent store coordinator loads a different data model
4. Codegen conflict — Xcode's automatic code generation conflicts with manually created subclass files

Fix 1: Set the Correct Module in the Data Model

This is the most common fix. In Xcode:

1. Open your .xcdatamodeld file
2. Select the entity
3. In the Data Model Inspector (right panel), check the Class section:
   • Name: Should match your Swift class name (e.g., Person)
   • Module: Set to Current Product Module (not blank, not a specific module name)

Entity: Person
Class Name: Person
Module: Current Product Module   ← This is critical

If the module field is blank or set to a wrong module, Core Data cannot find your class. For Swift, the full class name includes the module (e.g., MyApp.Person), and setting "Current Product Module" tells Core Data to use the app's module automatically.

Fix 2: Verify Entity and Class Names Match

The entity name in your data model and the class registered with Core Data must match:

1// Your entity in .xcdatamodeld is named "Person"
2// Your Swift class must match:
3
4@objc(Person)                          // Expose to Objective-C with this name
5class Person: NSManagedObject {
6    @NSManaged var name: String?
7    @NSManaged var age: Int16
8}

The @objc(Person) attribute is critical — without it, Swift mangles the class name (e.g., MyApp.Person), and Core Data may not find it.

Fix 3: Check Codegen Settings

Xcode can automatically generate NSManagedObject subclasses. Conflicts arise when you also have manual subclass files:

1. Select your entity in .xcdatamodeld
2. In the Data Model Inspector, check Codegen:
   • Class Definition: Xcode generates the full class. Do NOT create manual subclass files.
   • Category/Extension: Xcode generates properties as an extension. You create the class manually.
   • Manual/None: You manage everything manually.

1If Codegen = "Class Definition" and you have a manual Person.swift file:
2→ Duplicate symbol error or NSEntityDescription error
3
4Fix: Either delete your manual file or set Codegen to "Manual/None"

Clean Build After Changing Codegen

After changing codegen settings:

1. Product → Clean Build Folder (Shift+Cmd+K)
2. Delete the app from the simulator
3. Delete the DerivedData folder: ~/Library/Developer/Xcode/DerivedData/
4. Rebuild

Fix 4: Register the Managed Object Model Correctly

Ensure the persistent container loads the correct data model:

1// Standard setup with NSPersistentContainer
2let container = NSPersistentContainer(name: "MyDataModel")
3// The name must match your .xcdatamodeld filename (without extension)
4
5container.loadPersistentStores { description, error in
6    if let error = error {
7        fatalError("Failed to load Core Data: \(error)")
8    }
9}
10
11// Common mistake: wrong name
12let container = NSPersistentContainer(name: "MyApp")
13// If your file is "MyDataModel.xcdatamodeld", this WILL fail

Manual Model Loading

1// If you need to load the model manually:
2guard let modelURL = Bundle.main.url(forResource: "MyDataModel",
3                                      withExtension: "momd") else {
4    fatalError("Data model not found")
5}
6
7guard let model = NSManagedObjectModel(contentsOf: modelURL) else {
8    fatalError("Failed to load data model")
9}
10
11let coordinator = NSPersistentStoreCoordinator(managedObjectModel: model)

Fix 5: Creating Objects Correctly

Always create managed objects through the context, not with init():

1// CORRECT: Create through context
2let person = Person(context: managedObjectContext)
3person.name = "Alice"
4
5// CORRECT: Using NSEntityDescription
6let person = NSEntityDescription.insertNewObject(
7    forEntityName: "Person",
8    into: managedObjectContext
9) as! Person
10
11// WRONG: Direct initialization without context
12let person = Person()  // Crashes with NSEntityDescription error

Fix 6: Unit Testing Configuration

This error frequently appears in unit tests because the test target has a different module:

1// In your test setup:
2class CoreDataTests: XCTestCase {
3    var container: NSPersistentContainer!
4
5    override func setUp() {
6        super.setUp()
7
8        // Load model from the app bundle, not the test bundle
9        let bundle = Bundle(for: Person.self)
10        guard let modelURL = bundle.url(forResource: "MyDataModel",
11                                         withExtension: "momd"),
12              let model = NSManagedObjectModel(contentsOf: modelURL) else {
13            fatalError("Cannot load model")
14        }
15
16        container = NSPersistentContainer(name: "MyDataModel",
17                                          managedObjectModel: model)
18
19        // Use in-memory store for tests
20        let description = NSPersistentStoreDescription()
21        description.type = NSInMemoryStoreType
22        container.persistentStoreDescriptions = [description]
23
24        container.loadPersistentStores { _, error in
25            XCTAssertNil(error)
26        }
27    }
28}

Common Pitfalls

• Forgetting @objc(ClassName): Without this attribute, Swift uses the fully qualified name (e.g., MyApp.Person), which does not match the entity name Person in the data model. Always add @objc(EntityName) to your managed object subclasses.
• Module set to "Global namespace": In the Data Model Inspector, leaving the Module field blank defaults to the global namespace. For Swift classes, set it to "Current Product Module."
• Stale DerivedData: After changing entity names, codegen settings, or module configuration, Xcode may cache old generated files. Always clean DerivedData after model changes.
• Multiple data models: If your app has multiple .xcdatamodeld files, ensure you load the correct one. Creating an object whose entity lives in a different model than the context's coordinator will trigger this error.
• Migration issues: After renaming an entity, lightweight migration may fail if the mapping is not configured. Use a mapping model or NSEntityMigrationPolicy for entity renames.

Summary

• Set the entity's Module to "Current Product Module" in the Data Model Inspector
• Add @objc(EntityName) to your managed object subclass for correct Objective-C name exposure
• Match the entity name in .xcdatamodeld exactly with the class name in code
• Resolve codegen conflicts: use either Xcode-generated or manual subclass files, not both
• Always create managed objects via Person(context:) or NSEntityDescription.insertNewObject, never bare init()
• Clean DerivedData and rebuild after any data model configuration changes