TN3118: Debugging your app’s launch screen

Understand why your app’s launch screen is not displayed or updated.

Overview

A Launch Screen appears instantly when your app starts up and is quickly replaced with the app’s first screen, giving the impression that your app is fast and responsive. As you upgrade your application’s launch screen you may discover that the old version still appears or that it appears empty. This article explains possible reasons and how to fix them.

Launch screen does not display properly

Check why your launch screen fails to display:

iOS displays an outdated launch screen. Your new Xcode build has not overwritten the old launch screen. Clean your build folder for your project. In Xcode, select your target, then select the menu Product, menu item Clean Build Folder. Remove the app from device or Simulator. Build and run the app again.
iOS displays the last shown view controller. When your app enters the background, iOS takes a snapshot of the app, and displays the snapshot on subsequent launches. If you want your launch screen to appear again, remove your app from the device, and run it again from Xcode.

For SwiftUI-based or UIKit-based apps that use a launch screen in its Information Property List:

Your Info.plist is misconfigured. It is missing the UILaunchScreen key-value, or the UIImageName key-value does match with the image name what is found in the asset catalog. Be aware that case sensitivity is important.

For UIKit-based apps using a Storyboard Launch Screen:

The Launch Screen storyboard name doesn’t match what’s in the target settings. Select your Xcode target, goto the General tab, refer to the ‘App Icons and Launch Images’ section. The Launch Screen File setting should match the name of your launch screen storyboard found in the Project Navigator. To find out more about setting up your Launch Screen in Xcode, refer to Specifying your app’s launch screen.

[Image]

The image in your launch screen storyboard did not originate from the target’s asset catalog. If you are using static images in your launch screen, check to make sure the image originates from the product’s asset catalog as a JPG or PNG image.
Your Launch Screen storyboard’s initial view controller scene is not set as the initial view controller. Xcode will warn you: “Warning: Unsupported Configuration: ‘View Controller’ is unreachable because it has no entry points”. Select the view controller scene in your launch screen storyboard. Make sure Is Initial View Controller is checked.

[Image]

App launching with state restoration

Implement state restoration in your app so that the launch screen is used less often. iOS snapshots your app when it’s suspended and may use this snapshot instead of the launch screen the next time the app is launched. Users expect your app to be in the same state as when they left it. For more information on state restoration refer to About the UI restoration process.

Revision History

2023-07-25 Fixed some broken links.
2022-05-24 Made minor editorial changes.
2022-03-01 First published.