Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Flutter and app store releases

UIKit app crashes because it cannot find the storyboard

ErrorCould not find a storyboard named 'Main' in bundle NSBundle

Short answer

UIStoryboard throws this exception when no storyboard file with that name exists in the bundle it searches. The name must be written without the .storyboard extension. Compare the name in Info.plist and in your code with the real file, and make sure the file belongs to the bundle you ask, which is the main bundle when none is given.

  • Applies to Xcode 26, Swift 6, UIKit, iOS 26
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    List the storyboard files in the project and print the storyboard keys in Info.plist. The two names must match exactly, without the extension.

    find . -name "*.storyboard" -not -path "./Pods/*" -not -path "./build/*"
    plutil -p MyApp/Info.plist | grep -i storyboard
  2. 2Match what you see, then jump to its fix

    1. 1The crash happens at launch, before any of your own screens appearThe Info.plist key names a storyboard that does not existFix
    2. 2The crash happens when a button or segue code runs, and the stack shows UIStoryboard(name:bundle:)The name in your code does not match the fileFix
    3. 3The storyboard exists in the project, but sits in a framework or another target, not the app targetThe storyboard lives in a different bundleFix

What does the error look like?

  • Could not find a storyboard named 'Main' in bundle NSBundle

Cause 1 of 3

The Info.plist key names a storyboard that does not exist

1Check

UISceneStoryboardFile (inside the scene configuration) and UIMainStoryboardFile hold the storyboard's name. Apple says to give the name without the filename extension: for Main.storyboard the value is Main. A renamed or deleted storyboard, or a value written as Main.storyboard, leaves the key pointing at nothing.

plutil -p MyApp/Info.plist | grep -i -E "storyboard|UISceneConfigurations"
ls MyApp/*.storyboard MyApp/Base.lproj/*.storyboard 2>/dev/null

2Fix

Set the key to the existing file's base name. If the app should not use a storyboard at launch, delete the key and create the window in code instead.

<key>UISceneStoryboardFile</key>
<string>Main</string>

3Verify

Clean the build folder and launch again. The first screen shows instead of the crash.

xcodebuild -project MyApp.xcodeproj -scheme MyApp -destination 'generic/platform=iOS Simulator' clean build

Confirmed by developer.apple.com

Did this fix it?

Cause 2 of 3

The name in your code does not match the file

1Check

UIStoryboard(name:bundle:) takes the storyboard resource name without the extension. If no file with that name exists, UIKit throws this exact exception. Search the code for every place a storyboard is created.

grep -rn "UIStoryboard(name" --include=*.swift .

2Fix

Pass the real file name, and keep it in one constant so a rename cannot leave an old copy behind.

enum StoryboardName { static let main = "Main" }
let storyboard = UIStoryboard(name: StoryboardName.main, bundle: nil)

3Verify

Run the flow that creates the storyboard and confirm the screen opens.

grep -rn "StoryboardName" --include=*.swift .

Confirmed by developer.apple.com

Did this fix it?

Cause 3 of 3

The storyboard lives in a different bundle

1Check

When bundle is nil, UIStoryboard searches the main bundle of the running app. Apple also states that all resources a storyboard uses must be in the bundle you name. A storyboard that belongs to a framework target is not in the main bundle.

grep -n "Main.storyboard" MyApp.xcodeproj/project.pbxproj

2Fix

Pass the bundle that holds the file, for example the bundle of a class from the framework, and keep the storyboard and its images together in that bundle.

let bundle = Bundle(for: MyFrameworkViewController.self)
let storyboard = UIStoryboard(name: "Main", bundle: bundle)

3Verify

Run the screen that loads it and confirm the exception is gone.

# manual: open the screen from the framework in the running app

Confirmed by developer.apple.com

Did this fix it?

How do I stop it coming back?

  • Rename a storyboard through Xcode's navigator, then search Info.plist and the code for the old name.
  • Keep storyboard names in one place in code instead of repeating string literals.
  • When a storyboard moves into a framework, search for every UIStoryboard(name:) call and add the bundle.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Mobile apps

InstanceID token() no longer works in a Swift Firebase app

Instance ID calls fail to compile after upgrading Firebase to 8.0.0 or later

Firebase removed the Instance ID dependency from Messaging in 8.0.0, so InstanceID.instanceID() calls no longer belong in a current app.

3 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.