How to Fix Xcode ‘Could not instantiate class named’

When an app loads a Storyboard or XIB in Xcode, it may crash at runtime with an error such as “Could not instantiate class named …”. This usually means Interface Builder is trying to create a custom class that cannot be found in the built app.

What the error means

Could not instantiate class named MyViewController

Storyboards and XIB files store the Custom Class assigned to each view or view controller. If UIKit cannot resolve that class at runtime because the class no longer exists, the module is wrong, or the source file is not part of the current target, the app can fail with this message.

Common situations where it occurs

• You renamed a Swift class but the Storyboard still contains the old class name.
• You deleted a class file but a Storyboard or XIB still references it.
• The Module field in Identity Inspector points to an old project or another target.
• The Swift file is not included in the app target’s Target Membership.
• You moved the class into another framework or module.
• You copied a Storyboard from another project and its original module name remains.
• The class is not visible under the runtime name expected by Interface Builder.

What to check first

1. Identify the class name in the error

Look at the runtime console and note the class name. For example, this message means a Storyboard or XIB still contains a reference to MyViewController.

Could not instantiate class named MyViewController

2. Check the Custom Class in Interface Builder

Select the affected view controller or view, open Identity Inspector, and confirm that the Class and Module fields match the current Swift or Objective-C class.

3. Check Target Membership

Select the source file in the Project Navigator, open File Inspector, and make sure the running app target is checked under Target Membership.

Fix 1: Correct the Custom Class in the Storyboard

If you renamed the class, update the Storyboard or XIB to use the new name.

class MainViewController: UIViewController {
    override func viewDidLoad() {
        super.viewDidLoad()
    }
}

If the Swift class is MainViewController, the Class field in Identity Inspector should also be MainViewController.

Fix 2: Set the correct Module

Even if the class name is correct, Xcode may fail to instantiate it when the Module points to another target or an old project name. Set the Module field to the module that actually contains the class.

In many app targets, enabling “Inherit Module From Target” is the simplest way to keep the module aligned with the selected target.

Fix 3: Enable Target Membership

A class file can exist in the project but still be excluded from the built app. To fix that:

1. Select the Swift file in Project Navigator.
2. Open File Inspector.
3. Under Target Membership, check the app target you are running.
4. Build and run again.

Fix 4: Remove references to deleted classes

If a class was removed from the project, Interface Builder may still retain its old Custom Class value. Clear the Class field for objects that no longer need the custom subclass, or assign the correct replacement class.

Fix 5: Search the Storyboard as source code

If you cannot find where the stale class is assigned, open the Storyboard as source code and search for the class name shown in the error.

customClass="MyViewController"
customModule="OldProjectName"

If you find an outdated customClass or customModule, it is usually safer to correct the corresponding object through Interface Builder rather than manually editing XML.

Fix 6: Check classes moved to another framework or module

If you moved a custom view or view controller into a framework, update the Storyboard’s Module field to that framework. Also verify that the framework is linked and embedded correctly in the app target.

Fix 7: Verify the Objective-C runtime class name when needed

Storyboards and XIB files resolve classes by name at runtime. If your project depends on a specific Objective-C runtime name across module boundaries, you may need to expose the class explicitly.

@objc(MyCustomView)
class MyCustomView: UIView {
}

Fix 8: Clean the build and DerivedData

After fixing the configuration, use Clean Build Folder and rebuild. If stale build data remains, remove DerivedData and build again.

rm -rf ~/Library/Developer/Xcode/DerivedData/*

Then reopen Xcode and rebuild the project.

Search the project for stale class names

You can also search the whole project from Terminal to find references that may still exist in Storyboards, XIB files, or configuration files.

grep -R "MyViewController" .

Important notes

Summary

The “Could not instantiate class named” error occurs when a Storyboard or XIB references a custom class that the app cannot resolve at runtime. Start by checking the Class and Module fields in Identity Inspector, then verify Target Membership and remove stale references to deleted or renamed classes. If the setup is correct but the error persists, clean the build and remove DerivedData before rebuilding.