UIKit app crashes because it cannot find the storyboard
Could not find a storyboard named 'Main' in bundle NSBundleShort 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.
Fix it fast
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 storyboard2Match what you see, then jump to its fix
- 1
The crash happens at launch, before any of your own screens appearThe Info.plist key names a storyboard that does not existFix - 2
The 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
The storyboard exists in the project, but sits in a framework or another target, not the app targetThe storyboard lives in a different bundleFix
- 1
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/null2Fix
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 buildConfirmed by developer.apple.com
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
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.pbxproj2Fix
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 appConfirmed by developer.apple.com
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
UserDefaults logs 'Failed to read values in CFPrefsPlistSource' for an app group
Settings saved by the app are not visible to its extension, widget or sibling app that share the group
This log comes from the preferences system when UserDefaults is opened for an app group's suite.
3 causes, each with a fixMobile apps
iOS app crashes: Google Maps SDK must be initialized via provideAPIKey
Google Maps SDK for iOS must be initialized via [GMSServices provideAPIKey:...] prior to use
The Maps SDK throws this when a Maps object is created before GMSServices.provideAPIKey has run.
3 causes, each with a fixMobile apps
Firebase on iOS asks for the FCM token before APNs has given one
Be sure to re-retrieve the FCM token once the APNS device token is set.
The Firebase Messaging SDK needs the APNs device token from iOS before it hands out an FCM token.
3 causes, each with a fixMobile apps
A test push from the Firebase console never shows up on the iPhone
didReceiveRegistrationToken prints a token, yet no notification arrives
When a console message is accepted but the iPhone stays silent, the break is between Firebase and APNs or inside the app.
4 causes, each with a fixMobile 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 fixMobile apps
iOS launch screen with an asset catalog image or color does not appear
The launch image from the asset catalog never shows
iOS shows a launch screen only if the target defines one: a UILaunchScreen entry in Info.plist, or a launch storyboard chosen for the target.
3 causes, each with a fix