Introduction

The error "Failed to instantiate the default view controller for UIMainStoryboardFile 'Main' - perhaps the designated entry point is not set" means your iOS app cannot find an initial view controller in the Main storyboard. Every storyboard used as the app's entry point must have exactly one view controller marked as the "Initial View Controller." This is set via the arrow indicator in Interface Builder or the "Is Initial View Controller" checkbox in the Attributes inspector.

The Error

This crash occurs at launch with a message like:

Failed to instantiate the default view controller for
UIMainStoryboardFile 'Main' - perhaps the designated entry
point is not set?

The app launches to a black screen or crashes immediately.

Fix 1: Set the Initial View Controller in Storyboard

1. Open Main.storyboard in Xcode
2. Select the view controller you want as the entry point
3. Open the Attributes Inspector (right panel, shield icon)
4. Check "Is Initial View Controller"

You should see a gray arrow pointing to that view controller on the canvas. If the arrow is missing, no initial view controller is set.

Alternatively, drag the arrow from empty space to the target view controller directly on the storyboard canvas.

Fix 2: Verify Info.plist Configuration

The storyboard filename must match what is specified in your project settings:

<!-- Info.plist -->
<key>UIMainStoryboardFile</key>
<string>Main</string>

The value is the storyboard filename without the .storyboard extension. If your storyboard is named LaunchScreen.storyboard, the value should be LaunchScreen.

Check this in Xcode:

1. Select your project in the navigator
2. Select the target
3. Go to the General tab
4. Under Deployment Info, verify the Main Interface field shows the correct storyboard name

Fix 3: Set Entry Point Programmatically (No Storyboard)

If you prefer not to use a storyboard as the entry point, configure the root view controller in code:

UIKit (SceneDelegate)

1// SceneDelegate.swift
2func scene(_ scene: UIScene, willConnectTo session: UISceneSession,
3           options connectionOptions: UIScene.ConnectionOptions) {
4
5    guard let windowScene = scene as? UIWindowScene else { return }
6
7    let window = UIWindow(windowScene: windowScene)
8    window.rootViewController = UINavigationController(
9        rootViewController: HomeViewController()
10    )
11    window.makeKeyAndVisible()
12    self.window = window
13}

Then remove the storyboard reference:

1. Delete UIMainStoryboardFile from Info.plist
2. In General > Deployment Info, clear the Main Interface field
3. In the scene configuration in Info.plist, remove the storyboard name entry

UIKit (AppDelegate, pre-iOS 13)

1// AppDelegate.swift
2func application(_ application: UIApplication,
3                 didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
4
5    window = UIWindow(frame: UIScreen.main.bounds)
6    window?.rootViewController = HomeViewController()
7    window?.makeKeyAndVisible()
8    return true
9}

SwiftUI

SwiftUI apps using @main and App protocol do not use storyboards:

1@main
2struct MyApp: App {
3    var body: some Scene {
4        WindowGroup {
5            ContentView()
6        }
7    }
8}

If you see this error in a SwiftUI project, make sure Info.plist does not contain a UIMainStoryboardFile entry from an old template.

Fix 4: Storyboard Reference Issues

If your storyboard uses storyboard references pointing to other storyboards:

1// Verify the referenced storyboard exists and has an initial VC
2let storyboard = UIStoryboard(name: "Settings", bundle: nil)
3let vc = storyboard.instantiateInitialViewController()
4// Returns nil if no initial view controller is set

Each referenced storyboard also needs its own initial view controller if you are using instantiateInitialViewController().

Fix 5: Clean Build and Derived Data

Sometimes stale build artifacts cause this error even when the storyboard is configured correctly:

# Clean build folder in Xcode: Cmd+Shift+K
# Or delete derived data manually:
rm -rf ~/Library/Developer/Xcode/DerivedData/YourProject-*

Then rebuild the project (Cmd+B) and run again.

Checking Storyboard XML

If Interface Builder is not cooperating, verify the storyboard XML directly:

1<!-- Main.storyboard (right-click > Open As > Source Code) -->
2<document type="com.apple.InterfaceBuilder3.CocoaTouch.Storyboard.XIB"
3          version="3.0" ...>
4    <scenes>
5        <scene sceneID="tne-QT-ifu">
6            <!-- initialViewController must match a scene's id -->
7            <viewController id="BYZ-38-t0r"
8                            customClass="HomeViewController" ...>
9                ...
10            </viewController>
11        </scene>
12    </scenes>
13    <!-- This attribute on the <document> tag sets the initial VC -->
14    <!-- initialViewController="BYZ-38-t0r" -->
15</document>

The initialViewController attribute on the root <document> element must match the id of one of the view controllers. If this attribute is missing, no initial view controller is set.

Common Pitfalls

• Deleting the initial view controller and forgetting to reassign: If you delete the view controller that was marked as initial and add a new one, you must re-check "Is Initial View Controller" on the replacement.
• Storyboard name mismatch: The UIMainStoryboardFile value in Info.plist must exactly match the storyboard filename (without .storyboard). A typo like "main" instead of "Main" fails on case-sensitive file systems.
• Multiple storyboards with no initial VC: If you split your app into multiple storyboards, each storyboard used with instantiateInitialViewController() needs its own initial view controller.
• SwiftUI projects with leftover storyboard references: When converting from UIKit to SwiftUI, remove UIMainStoryboardFile from Info.plist and clear the Main Interface field in target settings.
• Corrupted storyboard file: Merge conflicts in .storyboard XML can remove the initialViewController attribute. After resolving merge conflicts, always verify the initial view controller is still set.

Summary

• The error means no view controller is marked as the initial entry point in the storyboard
• Check "Is Initial View Controller" in the Attributes Inspector for the target view controller
• Verify UIMainStoryboardFile in Info.plist matches your storyboard filename
• For programmatic setup, remove storyboard references and set window.rootViewController in SceneDelegate or AppDelegate
• Clean derived data if the configuration looks correct but the error persists