Maaz Zindani

Loading the index…

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

iOS launch screen with an asset catalog image or color does not appear

ErrorThe launch screen is black or blank before the first screen

Short answer

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. Check which one your target uses. Then make sure the image and color names match the asset catalog, or that the storyboard only uses what launch screens allow.

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

Fix it fast

  1. 1Find out which cause you have

    Find out what the built app declares. If neither key is in the app's Info.plist, no launch screen is configured.

    plutil -extract UILaunchScreen xml1 -o - path/to/MyApp.app/Info.plist; plutil -extract UILaunchStoryboardName raw -o - path/to/MyApp.app/Info.plist
  2. 2Match what you see, then jump to its fix

    1. 1plutil reports both keys as missingThe target declares no launch screenFix
    2. 2UILaunchScreen exists, but the screen shows no image or only the default backgroundUIImageName or UIColorName does not match the assetFix
    3. 3You use LaunchScreen.storyboard and it is ignored or blankThe launch storyboard uses something launch screens do not allowFix

What does the error look like?

  • The launch screen is black or blank before the first screen
  • The launch image from the asset catalog never shows

Cause 1 of 3

The target declares no launch screen

1Check

Apple says every iOS app must provide a launch screen, made either from an Info.plist entry or from a storyboard. Without either, nothing is configured.

plutil -extract UILaunchScreen xml1 -o - path/to/MyApp.app/Info.plist

2Fix

For a simple screen, add the UILaunchScreen key in the target's Info tab and add the sub-keys you want. For a storyboard, add a Launch Screen file from the template list and pick it under App Icons and Launch Screen in the General tab.

<key>UILaunchScreen</key>
<dict>
    <key>UIColorName</key>
    <string>LaunchBackground</string>
    <key>UIImageName</key>
    <string>LaunchLogo</string>
</dict>

3Verify

Delete the app from the device or simulator, then run it again.

# delete the app from the device or simulator, then run it again

Confirmed by developer.apple.com

Did this fix it?

Cause 2 of 3

UIImageName or UIColorName does not match the asset

1Check

UIColorName is the name of the color used as the background and UIImageName is the name of the image shown. Open the asset catalog and compare the exact asset names, including case, with the strings in the plist.

plutil -extract UILaunchScreen xml1 -o - path/to/MyApp.app/Info.plist

2Fix

Make the plist strings identical to the names of the image set and color set in the asset catalog. Add UIImageRespectsSafeAreaInsets if the image must stay inside the safe area.

<key>UIImageRespectsSafeAreaInsets</key>
<true/>

3Verify

Uninstall, rebuild and launch. The image and background color should appear before the first screen.

# delete the app from the device or simulator, then run it again

Confirmed by developer.apple.com

Did this fix it?

Cause 3 of 3

The launch storyboard uses something launch screens do not allow

1Check

Apple's rules for a launch storyboard: only UIKit classes, a single root object that is a UIView or UIViewController, no connections to code, no custom classes, no runtime attributes and no deprecated views. Open the storyboard and look for any of these.

grep -nE "customClass|runtimeAttributes|outlet|action selector" LaunchScreen.storyboard

2Fix

Remove custom classes, outlets, actions and runtime attributes from the launch storyboard. Keep one root view, and build the layout with Auto Layout.

# no code: edit LaunchScreen.storyboard in Interface Builder

3Verify

Uninstall the app and run it again.

# delete the app from the device or simulator, then run it again

Confirmed by developer.apple.com

Did this fix it?

How do I stop it coming back?

  • Pick one method per target, plist or storyboard, and record it in the project README.
  • Keep launch assets in a named asset catalog set and avoid renaming it without updating Info.plist.
  • Delete the app before judging a launch screen change.

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.