Fix .NET MAUI iOS 27 Launch Crashes in Xcode 27: Add the Required Scene Lifecycle

This isn't a MAUI bug. It's a platform rule from Apple, and the fix for a simple app is two files. The harder part is everything else your app does at launch, such as authentication callbacks, deep links and App Actions.

What changed, and who is affected​

The iOS and iPadOS 27 release notes say apps built with the latest SDK must adopt the scene-based life cycle or they fail to launch. The .NET for iOS release notes say the same thing. Apple's requirement means apps that haven't adopted scenes crash at launch when built with Xcode 27.

Three scoping points matter:

• The trigger is the SDK you build with. The check is tied to the SDK, not the iOS version on the phone. An app built with Xcode 26 still launches on iOS 27. Microsoft's guidance agrees that an existing binary built with an older SDK doesn't need migrating just because someone updates their phone.
• It applies to iOS and Mac Catalyst. The .NET release notes list both as affected, and Microsoft's lifecycle documentation tells you to update both Platforms/iOS and Platforms/MacCatalyst.
• It isn't specific to the iPhone Duo. Microsoft stresses that any iOS app built with Xcode 27, on any form factor, needs this pattern.

The history helps explain why many apps are caught out. Since iOS 13, UIKit has offered a scene lifecycle. The app delegate only bootstraps the process, and a scene delegate owns each window. For seven years the legacy path kept working. Updating the MAUI packages or workloads doesn't rewrite your platform files, so older projects can still be on the legacy path.

Step 1: Check your toolchain​

Don't change code until your versions line up.

• Workload and Xcode. The released .NET 10 iOS and Mac Catalyst workloads, version 27.0.10722, require Xcode 27.0. The macios release notes add that Xcode 27.0 requires macOS 26.6 or later. A newer Xcode doesn't automatically work with that workload, so use the matching versions instead of disabling the SDK's Xcode check.
• Quick check. maui doctor reports your active .NET SDK, MAUI workload, selected Xcode and Apple SDK compatibility. It also checks the Xcode license, command-line tools and installed iOS runtimes.
• MAUI package version. For a .NET 10 app, Microsoft recommends 10.0.110 or higher before enabling scenes. The two-file fix works on older MAUI versions, but 10.0.110 adds scene-side App Actions dispatch and WebAuthenticator forwarding. Skip the update and you may fix the launch while quietly breaking those features. The macios release notes also say MAUI SR 11 (10.0.110 or later) is recommended with this release.
• Pinning the version. Template projects usually take $(MauiVersion) from the installed workload. To pin it, put <MauiVersion>10.0.110</MauiVersion> in a PropertyGroup in your .csproj. Don't downgrade a newer version you already have.

You may already be done. If you have a MauiUISceneDelegate and a matching scene manifest, skip the migration steps. You should still test on iOS 27. Apps created from the 10.0.110 templates already include the configuration.

Step 2: Add the scene delegate​

Create Platforms/iOS/SceneDelegate.cs. If one already exists, check its base class and registration rather than adding a second.

using Foundation;
using Microsoft.Maui;

namespace MyMauiApp;

[Register("SceneDelegate")]
public class SceneDelegate : MauiUISceneDelegate
{
}

Replace MyMauiApp with your own namespace. Keep the class public. Leave your existing AppDelegate : MauiUIApplicationDelegate in place, because the scene delegate works alongside it. MAUI does the window setup.

Step 3: Add the scene manifest​

Open Platforms/iOS/Info.plist as XML and add this inside the root <dict>. If a UIApplicationSceneManifest already exists, update it instead of adding a duplicate.

<key>UIApplicationSceneManifest</key>
<dict>
  <key>UIApplicationSupportsMultipleScenes</key>
  <false/>
  <key>UISceneConfigurations</key>
  <dict>
    <key>UIWindowSceneSessionRoleApplication</key>
    <array>
      <dict>
        <key>UISceneConfigurationName</key>
        <string>__MAUI_DEFAULT_SCENE_CONFIGURATION__</string>
        <key>UISceneDelegateClassName</key>
        <string>SceneDelegate</string>
      </dict>
    </array>
  </dict>
</dict>

Four details decide whether this works:

• Keep the configuration name exactly. __MAUI_DEFAULT_SCENE_CONFIGURATION__ is the name MAUI expects when it creates the window. A different name needs a custom implementation that handles window creation.
• Match the delegate name. The value in the plist must equal the [Register] name in C#.
• Leave multiple scenes off. Keep UIApplicationSupportsMultipleScenes false unless your app really supports multiple windows. Scene adoption doesn't require them.
• Don't add a storyboard. Skip UISceneStoryboardFile, and leave your MauiSplashScreen or UILaunchStoryboardName setup alone.

If you override GetConfiguration or WillConnect, or use custom configuration names, review those together with the manifest. Don't replace the manifest wholesale.

Check every plist. Some apps use different plists for Debug, Release, customer or environment builds. Add or reconcile the manifest in every plist that can produce a shipping app. Update only the default file and one configuration can still crash right after the splash screen.

Mac Catalyst. Repeat both changes: Platforms/MacCatalyst/SceneDelegate.cs and the same manifest in Platforms/MacCatalyst/Info.plist.

Step 4: Check minimum OS versions​

The .NET 27 SDKs raise the floors. iOS needs at least 15.0, and Mac Catalyst needs at least 17.0 (macOS 14 Sonoma). Update your SupportedOSPlatformVersion entries inside a PropertyGroup if they're lower:

<SupportedOSPlatformVersion Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'ios'">15.0</SupportedOSPlatformVersion>
<SupportedOSPlatformVersion Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'maccatalyst'">17.0</SupportedOSPlatformVersion>

Replace existing values rather than duplicating them, because a later definition can override yours. Keep each value free of leading or trailing whitespace. Keep a higher target if you already have one.

If you must support iOS below 15, or macOS 12 and 13, you face a support-policy decision. Microsoft's advice is to stay on a compatible 26.x SDK while you decide, not to drop those users silently.

Apple's App Store page also sets a later deadline. Apple's page says that starting in April 2027, iOS and iPadOS uploads must be built with the 27 SDK or later and target iOS 15 or later. That deadline is separate from the launch crash, which applies to any app built with the new SDK.

Step 5: Audit your custom behavior​

Enabling scenes changes which callbacks fire. UIKit stops calling the AppDelegate activation, backgrounding, URL and user-activity callbacks. That covers both ConfigureLifecycleEvents registrations and AppDelegate overrides such as OpenUrl or ContinueUserActivity.

The callback arguments differ, so move the logic instead of just renaming the registration. Microsoft's documentation adds that SceneDidDisconnect is the place for window cleanup, and WillTerminate stays an application-level callback. If you override methods in your own SceneDelegate, call the base implementation. MAUI's window setup, lifecycle events and authentication forwarding depend on it.

Cold-start links and activity​

• Cold launches. When the app is launched by a link, inspect connectionOptions.UrlContexts, UserActivities and ShortcutItem in SceneWillConnect. MAUI doesn't replay those through SceneOpenUrl or SceneContinueUserActivity.
• Timing. SceneWillConnect runs before MAUI creates the window. Keep the data and navigate once the window exists.
• Warm links. A connected scene gets URLs through SceneOpenUrl and user activities through SceneContinueUserActivity. This works even with multiple scenes disabled.
• Notification taps. Inspect connectionOptions.NotificationResponse as another cold-start input. Push registration and DidReceiveRemoteNotification remain application-level.
• Null guards. A normal launch may carry no URL or activity payload. Guard against absent UrlContexts and UserActivities before enumerating, even if the binding suggests a value.
• AppDelegate.Window. FinishedLaunching still runs, but the window is created later by the scene delegate, so AppDelegate.Window stays null. Code that touches it after base.FinishedLaunching needs to use the scene window once it is ready.

Authentication​

MAUI forwards warm scene URL contexts and user activities that carry a WebPageUrl to WebAuthenticator callback handling. That bridge isn't general deep-link navigation. It also doesn't process cold-connection payloads, so you need your own handlers for app links. Test both authentication and your own links with the app running and fully closed.

App Actions​

Every custom PerformActionForShortcutItem handler must call its completion callback exactly once. Pass true if the action was handled and false if it wasn't. A handler can respond asynchronously, but returning alone doesn't acknowledge the action.

Even a log-only handler must respond. The default MAUI builder already forwards App Actions to Essentials, so don't add another Platform.PerformActionForShortcutItem registration. If your AppDelegate overrides PerformActionForShortcutItem, that override is no longer called once scenes are on. Move the logic into a lifecycle registration in MauiProgram.cs, with the Microsoft.Maui.LifecycleEvents using directive and the completion call included.

Step 6: Rebuild and test properly​

dotnet restore -p:TargetFramework=net10.0-ios
dotnet build -f net10.0-ios --no-restore

If the simulator still seems to run an old build, uninstall the app, delete the project's bin and obj folders, and run both commands again.

Then test on a regular iPhone or iPad simulator running iOS 27, with the matching workload and Xcode:

1. Launch both Debug and Release builds cold.
2. Send the app to the background and bring it back.
3. Run your authentication flow.
4. Open links and tap notifications with the app both running and closed.
5. Use any App Actions.
6. Build and exercise the Mac Catalyst target if you ship one.

A successful build, or a launch on iOS 26, proves very little here. You don't need an iPhone Duo simulator. Microsoft says device-specific layouts and Xcode 27.1 tooling will be covered in a follow-up.

The optional AI migration skill​

Microsoft also describes a maui-xcode27-migration agent skill. You install it with the .NET MAUI CLI, and your coding agent does the work. The CLI itself edits nothing, and there is no maui migrate command. Microsoft lists these requirements:

• Microsoft.Maui.CLI version 0.1.0-preview.13.26512.5 or later
• Install with dotnet tool install --global Microsoft.Maui.Cli --version 0.1.0-preview.13.26512.5, or use dotnet tool update for an existing install
• From your app's repository, run maui ai list skill, then maui ai add skill maui-xcode27-migration --env CopilotCli --yes
• Restart your agent session afterward

The CLI and skill are experimental and not covered by the Microsoft Support Policy. They need network access to reach the public dotnet/maui-labs catalog. I only confirmed that the repository exists and is described as experimental and pre-release MAUI tooling. I didn't independently verify the exact commands or version number, which come from Microsoft's post.

Commit your work first and read the full diff afterward. Ask the agent to preserve custom lifecycle behavior, and to check with you before changing the SDK or dropping older OS support. A green build won't tell you whether an OAuth redirect or a Home screen shortcut still works.

What to take from this​

• MAUI is not at fault. This is Apple's rule, and it ties to the SDK you build with. Existing builds from older SDKs keep working.
• Other frameworks are hit too. Community reports show Expo and React Native projects failing with the same launch error. The pattern is broad, and the cost lands on legacy projects.
• A simple app takes minutes. A mature one takes a test plan. The risk sits in cold-start links, notification routing and shortcuts, and builds and launches won't catch those.

If you haven't touched your platform folders since the early .NET MAUI days, do this before Xcode 27 ends up in your CI image. Doing it afterward means finding out from a crash.