Flutter UIScene Migration: Fix iOS 27 Launch Crashes

If your Flutter app opens to a blank screen and then quits as soon as you build it with Xcode 27, the cause is almost always the same: the app hasn't adopted the UIScene lifecycle. This Flutter UIScene migration guide covers what Apple changed, which apps Flutter migrates for you, and the manual steps for apps with a custom AppDelegate, method channels or lifecycle-dependent plugins.

What changed in iOS 27 and Xcode 27

UIKit has had two lifecycles since iOS 13: the older app delegate lifecycle, where AppDelegate owns the window and gets events like applicationDidBecomeActive, and the scene-based lifecycle, where each window lives in a UIWindowScene with its own delegate.

Apple has warned about this for a while. Its UIKit documentation notes that iOS 18.4 started logging "This process does not adopt UIScene lifecycle" and iOS 26 changed it to "UIScene lifecycle will soon be required". From iOS 27, apps built with the latest SDK must adopt the scene-based lifecycle "or they fail to launch".

In practice the failure looks like this in the Xcode console, taken from Flutter's own tracking issue:

Application failed to launch: UIScene life cycle is required for apps built with this SDK.
See Technote TN3187 for more information on migration.

Two details catch people out:

• It depends on the SDK you build with, not the device. An app built with Xcode 26 keeps working on iOS 27. The same code built with Xcode 27 stops at launch on every device.
• It isn't Flutter specific. Any UIKit app without a scene manifest is affected. React Native added SceneDelegate support in 0.88 for the same reason.

Flutter's team reproduced it with their own test apps during the Xcode 27 beta (issue #187870, a Flutter 3.44.1 app on iPadOS 27).

Which Flutter apps need manual work

Flutter added the scene APIs in 3.38 and made UIScene the default in 3.41, which also auto-migrates eligible projects (Flutter breaking change: UIScene adoption). Here's where your project probably sits:

"Custom AppDelegate" covers more apps than people expect. If you ever added a method channel, a Google Maps API key, a push notification setup, a background task or a deep link handler in AppDelegate.swift, you're in the manual group.

The diagram is the key idea. Plugin registration and anything that touches the Flutter view now happen after the scene connects, not inside didFinishLaunchingWithOptions.

Step 1: upgrade Flutter and try the automatic migration

Start on a branch, upgrade, and let the tool try first. At the time of writing, the current stable release is 3.47.7 (8 October 2026).

git checkout -b uiscene-migration
flutter upgrade
flutter --version
flutter clean && flutter pub get
flutter build ios --no-codesign
git diff -- ios/

If the output includes "Finished migration to UIScene lifecycle", review the changes to AppDelegate.swift and Info.plist, run the app, and skip to the testing checklist.

A useful trick when the CLI refuses: generate a fresh reference project with the same Flutter version and diff the iOS runner files against yours.

flutter create --platforms=ios /tmp/uiscene_reference
diff -u /tmp/uiscene_reference/ios/Runner/AppDelegate.swift ios/Runner/AppDelegate.swift
diff -u /tmp/uiscene_reference/ios/Runner/Info.plist ios/Runner/Info.plist

In Flutter 3.47 the template already ships an AppDelegate that conforms to FlutterImplicitEngineDelegate, a SceneDelegate.swift, and a scene manifest in Info.plist.

Step 2: Flutter UIScene migration for a custom AppDelegate

The main change is where plugins and channels get registered. Conform AppDelegate to FlutterImplicitEngineDelegate and move plugin registration, method channels and platform view factories into didInitializeImplicitFlutterEngine.

Here's a typical migrated AppDelegate with one method channel:

import Flutter
import UIKit

@main
@objc class AppDelegate: FlutterAppDelegate, FlutterImplicitEngineDelegate {
  override func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
  ) -> Bool {
    // Keep only process-level setup here, such as BGTaskScheduler
    // registration, which must happen before launch finishes.
    // Do not touch window or FlutterViewController here.
    return super.application(application, didFinishLaunchingWithOptions: launchOptions)
  }

  func didInitializeImplicitFlutterEngine(_ engineBridge: FlutterImplicitEngineBridge) {
    GeneratedPluginRegistrant.register(with: engineBridge.pluginRegistry)

    let deviceChannel = FlutterMethodChannel(
      name: "com.example.app/device",
      binaryMessenger: engineBridge.applicationRegistrar.messenger()
    )
    deviceChannel.setMethodCallHandler { call, result in
      switch call.method {
      case "batteryLevel":
        UIDevice.current.isBatteryMonitoringEnabled = true
        result(Int(UIDevice.current.batteryLevel * 100))
      default:
        result(FlutterMethodNotImplemented)
      }
    }
  }
}

The pattern to remove is the one in most older tutorials:

// Crashes or returns nil after migration: the window doesn't exist yet
let controller = window?.rootViewController as! FlutterViewController

Use engineBridge.applicationRegistrar.messenger() for channels instead. If you really need the view controller itself, the guide suggests subclassing FlutterViewController and doing the work in awakeFromNib, or doing it in the scene delegate.

Step 3: add the scene manifest to Info.plist

Without this entry iOS never creates a scene, so nothing changes. Add it to ios/Runner/Info.plist:

<key>UIApplicationSceneManifest</key>
<dict>
  <key>UIApplicationSupportsMultipleScenes</key>
  <false/>
  <key>UISceneConfigurations</key>
  <dict>
    <key>UIWindowSceneSessionRoleApplication</key>
    <array>
      <dict>
        <key>UISceneClassName</key>
        <string>UIWindowScene</string>
        <key>UISceneConfigurationName</key>
        <string>flutter</string>
        <key>UISceneDelegateClassName</key>
        <string>FlutterSceneDelegate</string>
        <key>UISceneStoryboardFile</key>
        <string>Main</string>
      </dict>
    </array>
  </dict>
</dict>

Step 4: move UI lifecycle code out of AppDelegate

After migration, UIKit stops calling the UI state methods on the app delegate: applicationDidBecomeActive, applicationWillResignActive, applicationWillEnterForeground, applicationDidEnterBackground and application(_:open:options:).

Create a SceneDelegate that subclasses FlutterSceneDelegate, so Flutter keeps forwarding scene events to the engine and plugins:

import Flutter
import UIKit

class SceneDelegate: FlutterSceneDelegate {
  private var observers: [NSObjectProtocol] = []

  override init() {
    super.init()
    observers.append(
      NotificationCenter.default.addObserver(
        forName: UIScene.didActivateNotification,
        object: nil,
        queue: .main
      ) { _ in
        // Work that used to live in applicationDidBecomeActive,
        // for example clearing the badge or refreshing a token.
      }
    )
  }
}

Then point the manifest at it by changing UISceneDelegateClassName to $(PRODUCT_MODULE_NAME).SceneDelegate, which is what the 3.47 template uses.

Observing UIScene notifications is the least invasive option and leaves Flutter's own forwarding alone. If you need full control and can't subclass FlutterSceneDelegate, the Flutter guide shows how to forward each event with FlutterSceneLifeCycleProvider and FlutterPluginSceneLifeCycleDelegate.

Often the cleaner fix is to move the logic to Dart. App-level "resumed" and "paused" handling usually belongs in an AppLifecycleListener anyway, where it works the same on Android.

Plugins: the part you don't control

Plugins that listen for app lifecycle events, open URLs or user activities need to register for scene events too. Flutter's guide asks plugin authors to adopt FlutterSceneLifeCycleDelegate and call registrar.addSceneDelegate(instance), and to stop relying on UIApplication.shared.delegate.window, which is nil after migration.

For an app, that means:

1. Run flutter pub outdated and update plugins, especially anything for deep links, auth redirects, notifications, maps and payments.
2. Read the changelogs for "UIScene" or "scene" entries.
3. For in-house plugins, follow the plugin section of the Flutter guide. The APIs need Flutter 3.38 or later.

UIScene migration testing checklist

Build with Xcode 27 and test on a real device, not only the simulator:

• Cold launch from the home screen shows your first screen, not a blank window.
• Method channels respond (call each one at least once).
• Deep links and universal links open the right screen from a cold start and from the background.
• Auth redirects (Sign in with Apple, Google, OAuth web flows) return to the app.
• Push notifications arrive, and tapping one opens the right screen.
• Background tasks still register (check the console for BGTaskScheduler errors).
• Code that used to run in applicationDidBecomeActive still runs when you return to the app.
• In-app purchases complete and restore. If you sell subscriptions, also check that server-side verification still runs (more on that in my StoreKit subscriptions post).
• The console no longer prints the "UIScene lifecycle will soon be required" warning.
• An iPad build works if you support iPad, since scene windows can be resized there.

When I take over an existing Flutter app, a custom AppDelegate is one of the first things I look at. It's where small native changes pile up over the years, and this migration touches all of them. My notes on taking over a live Flutter and PHP app explain how I approach that kind of audit.