Fix: Programmatically Set Initial View Controller in Storyboard

Written by

in

Quick answer: Uncheck Is Initial View Controller in the storyboard, give each candidate view controller a Storyboard ID, clear Main Interface and Main storyboard file base name, then create the UIWindow and set window.rootViewController to the controller you instantiate with instantiateViewController(withIdentifier:) in application:didFinishLaunchingWithOptions: or scene:willConnectTo:.

Choosing a different first screen at launch is common for login checks, onboarding, or A/B flows. Storyboards normally have a fixed entry point arrow, so you need to take control of window creation and set rootViewController yourself.

Why this happens

A storyboard marks one view controller as Is Initial View Controller. That arrow tells UIKit which controller to instantiate automatically when the app loads the value of UIMainStoryboardFile (also shown as Main storyboard file base name in Info.plist and Main Interface under Target > General).

If you want the first screen to vary by condition, that static entry point does not work. You cannot change the arrow at runtime. You have to disable the automatic loading and create the window and root controller in code.

If you simply uncheck Is Initial View Controller without removing the Info.plist / Main Interface entry, UIKit still tries to load the storyboard’s default controller and fails with:

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

At that point window is also nil because the system did not create it for you. You must create the UIWindow yourself and assign its rootViewController before calling makeKeyAndVisible().

How to fix it

1. Prepare the storyboard and project settings

This is the same for Objective-C and Swift.

  1. Open your storyboard. Select each view controller that might be the first screen and set a Storyboard ID in the Identity inspector. For example LoginViewController -> LoginVC, MainViewController -> MainVC. Check Use Storyboard ID if needed.
  2. Select the controller that currently has the entry arrow and uncheck Is Initial View Controller in the Attributes inspector. No controller should have the arrow now.
  3. Remove the automatic storyboard loading. You need to do both places where Xcode stores it:
    * Target > Info > Main storyboard file base name (UIMainStoryboardFile) – delete the value.
    * Target > General > Main Interface – clear the value.
    * If you have Info.plist open as source, remove the UIMainStoryboardFile and UIMainStoryboardFile~ipad keys.

Build now and you will see the error above until you implement step 2 or 3. That is expected.

2. Create the window and set rootViewController in AppDelegate (iOS 12 and earlier, or apps without SceneDelegate)

For projects that still use AppDelegate to own the window, create the window in application:didFinishLaunchingWithOptions:.

Swift:

import UIKit

@main
class AppDelegate: UIResponder, UIApplicationDelegate {

    var window: UIWindow?

    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {

        window = UIWindow(frame: UIScreen.main.bounds)

        let storyboard = UIStoryboard(name: "Main", bundle: nil)

        // Decide which controller to show
        let isLoggedIn = UserDefaults.standard.bool(forKey: "isLoggedIn")
        let identifier = isLoggedIn ? "MainVC" : "LoginVC"

        let initialViewController = storyboard.instantiateViewController(withIdentifier: identifier)

        window?.rootViewController = initialViewController
        window?.makeKeyAndVisible()

        return true
    }
}

Objective-C:

#import "AppDelegate.h"

@implementation AppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    self.window = [[UIWindow alloc] initWithFrame:UIScreen.mainScreen.bounds];

    UIStoryboard *storyboard = [UIStoryboard storyboardWithName:@"Main" bundle:nil];

    BOOL isLoggedIn = [[NSUserDefaults standardUserDefaults] boolForKey:@"isLoggedIn"];
    NSString *identifier = isLoggedIn ? @"MainVC" : @"LoginVC";

    UIViewController *viewController = [storyboard instantiateViewControllerWithIdentifier:identifier];

    self.window.rootViewController = viewController;
    [self.window makeKeyAndVisible];

    return YES;
}

@end

Key points:

  • Use the storyboard name without the .storyboard extension. If your file is Main.storyboard, the name is "Main".
  • instantiateViewController(withIdentifier:) requires the exact Storyboard ID. A typo crashes with could not find a view controller with identifier.
  • If your initial controller should be embedded in a navigation controller, either give the UINavigationController itself a Storyboard ID and instantiate that, or wrap the controller in code: UINavigationController(rootViewController: initialViewController).

3. Do the same in SceneDelegate for iOS 13+

If your project uses scenes (Xcode 11+ template), AppDelegate no longer owns the window. The window is created in SceneDelegate.swift. Leave AppDelegate alone and implement scene:willConnectTo:.

import UIKit

class SceneDelegate: UIResponder, UIWindowSceneDelegate {

    var window: UIWindow?

    func scene(_ scene: UIScene, willConnectTo session: UISceneSession, options connectionOptions: UIScene.ConnectionOptions) {
        guard let windowScene = scene as? UIWindowScene else { return }

        let window = UIWindow(windowScene: windowScene)
        let storyboard = UIStoryboard(name: "Main", bundle: nil)

        let isOnboarded = UserDefaults.standard.bool(forKey: "hasSeenOnboarding")
        let identifier = isOnboarded ? "MainVC" : "OnboardingVC"

        let initialViewController = storyboard.instantiateViewController(withIdentifier: identifier)

        window.rootViewController = initialViewController
        self.window = window
        window.makeKeyAndVisible()
    }
}

You still need to clear Main Interface and UIMainStoryboardFile. Do not delete the UISceneStoryboardFile entry that Xcode adds under Application Scene Manifest if you are fully moving to programmatic scenes – instead, remove the Storyboard Name for the scene configuration or leave it empty so the scene does not try to load a storyboard automatically.

If you keep a storyboard name in the scene manifest, the system will create a window and root controller before your code runs, and your assignment will replace it. Clearing it avoids that double work.

4. Alternative: Keep a dummy initial controller

Some teams prefer to keep an entry point to avoid touching Info.plist. In that pattern you leave one controller checked as Is Initial View Controller, make it a lightweight UIViewController with no UI, and in its viewDidLoad or application:didFinishLaunchingWithOptions: you immediately replace window.rootViewController.

This works but causes a brief flash of the dummy controller and adds an extra controller to maintain. The clean approach above – no initial arrow and manual window creation – avoids the flash and the warning Failed to instantiate the default view controller... entirely.

How to prevent it

  • Give every view controller that could be an entry point a stable Storyboard ID and document the IDs in one place. Renaming a controller in code without updating the storyboard breaks the launch.
  • Decide early whether your app uses AppDelegate window or SceneDelegate window and put the logic in only one place. Duplicating it in both causes the second assignment to overwrite the first.
  • If you wrap the initial controller in a UINavigationController or UITabBarController in code, do not also embed it in the storyboard. Pick one method.
  • After clearing Main Interface, test a clean build and a fresh install. Cached launch storyboards can hide a missing makeKeyAndVisible() call until the next cold launch.
  • Keep storyboard names and identifiers as constants to avoid string typos:
enum StoryboardID {
    static let main = "Main"
    static let login = "LoginVC"
    static let mainApp = "MainVC"
}

FAQ

Do I have to delete the Main storyboard entry from Info.plist?

Yes if you use the no-dummy-controller approach. If UIMainStoryboardFile or Main Interface still points to a storyboard that has no initial view controller, the app will crash at launch with Failed to instantiate the default view controller.... Clearing both entries tells UIKit you will provide the window yourself.

Why is my window nil or the screen stays black?

You created a local UIWindow but did not assign it to self.window (or SceneDelegate.window) and did not call makeKeyAndVisible(). The window is deallocated immediately and nothing is displayed. Always store it in the delegate’s window property before making it key and visible.

How do I set a navigation controller as the initial controller programmatically?

Give the UINavigationController in the storyboard its own Storyboard ID, for example MainNav, and instantiate that ID. Or instantiate the content controller and wrap it: let nav = UINavigationController(rootViewController: storyboard.instantiateViewController(withIdentifier: "MainVC")) then window.rootViewController = nav. Use the first option if the navigation stack is already designed in the storyboard.

Sources & credits

Parts of this guide are adapted from content licensed under CC BY-SA 3.0; this article is shared under the same license.