[iOS ANR]: iOS white/black screen after long background (UIScene + Impeller)

[kwongfung]

Summary

On iOS, when the app has been in the background for a long time (e.g. 30+ minutes, or after prolonged music playback in another app), returning to the app often results in a white or black screen with no Flutter UI. The process is running and the system reports the app as visible and active, but nothing is rendered. Force-quitting and relaunching usually fixes it until the next long background.

Environment

• Flutter: 3.38.9 (stable)
• Platform: iOS (physical device; issue is rare or absent on simulator)
• Architecture: Standard Flutter app with UIScene lifecycle (SceneDelegate), single window
• Rendering: Impeller (default on iOS since 3.29; Skia not available)
• Reproduction: More likely after long background and/or when another app (e.g. music) has been in foreground

Steps to reproduce

1. Launch the Flutter app on a physical iOS device.
2. Send the app to background (home or app switcher).
3. Leave the device with the app in background for a long time (e.g. 30+ minutes), optionally with another app (e.g. music) in foreground.
4. Bring the Flutter app back to foreground (tap icon or from app switcher).

Result: Screen stays white (or black). No Flutter content is drawn. App does not crash; it just fails to render.

Expected: App should show the last screen or the appropriate UI after resume.

Observations from system logs

• SpringBoard / runningboard report the app as running-active, Visible, and UserInteractiveFocal.
• Scene lifecycle reaches Foreground and scene content state becomes ready.
• Runner (the app process) sometimes reports itself as unknown-NotVisible or running-active-NotVisible in RBS/state updates while the system considers the app visible—suggesting an internal visibility or rendering-pipeline mismatch.
• Logs often contain: Returning cached initialization context (warm/resume path) and sometimes updated settings were not derived from the scene's previous settings.
• No Flutter or engine crash; the failure is “no frame painted” rather than a crash.

Suspected root cause (for implementers)

We believe this is related to Impeller/Metal surface lifecycle after long background:

1. Surface invalidation: After long background, iOS may reclaim or invalidate GPU/Metal resources (CAMetalLayer, drawables, or context). The Flutter engine’s Metal surface may no longer be valid.
2. No automatic surface recreation: Engine creates the surface in viewDidLayoutSubviews when the app is active. If the view’s bounds do not change on resume, layout may not run again, so the engine never recreates the surface and keeps using an invalid one → nothing is drawn.
3. Frame vs. surface timing: When the app becomes active, Dart receives resumed and typically calls scheduleFrame() once. If the Metal surface is recreated asynchronously and the first frame is requested before the new surface is ready, that frame can be dropped and no further frame is scheduled → prolonged white/black screen.

So the issue likely combines: (a) surface invalidation after long background, (b) no bounds change so no viewDidLayoutSubviews-driven surface recreation, and (c) first frame scheduled too early relative to surface readiness.

Workarounds we use (app-side)

We cannot fix the engine from the app; the following only mitigate:

1. Force surface invalidation (SceneDelegate): On sceneWillEnterForeground and sceneDidBecomeActive, we temporarily change the Flutter view’s frame (e.g. insetBy(dx: 0, dy: 0.5) then restore) so the engine sees a bounds change and recreates the surface in viewDidLayoutSubviews. We repeat this at 0.3s, 0.6s, 1s, 2s, 3s to cover slow GPU recovery.
2. Multiple delayed scheduleFrame() (Dart): In WidgetsBindingObserver.didChangeAppLifecycleState(resumed), we call WidgetsBinding.instance.scheduleFrame() immediately and again at 100, 500, 1000, 2000, 3000, 4000, 5000, 6000, 8000 ms so that at least one frame request happens after the new surface is ready.
3. runApp first: We avoid blocking runApp() on async init (e.g. Firebase, Prefs) so the first frame is scheduled as soon as possible; heavy init runs after the first frame.
4. FLTDisablePartialRepaint (Info.plist): We set this to YES as a possible mitigation for partial-repaint-related glitches; it may or may not help this specific issue.

These workarounds reduce but do not fully eliminate the problem, especially after very long background (e.g. hours) or under memory pressure.

What we are asking for

• Engine / framework: Ensure that when the app returns to foreground after long background, the Impeller/Metal surface is recreated or revalidated (e.g. in response to scene activation or a guaranteed layout pass), and that at least one frame is scheduled after the new surface is ready, so that Flutter UI is drawn without app-side hacks.
• Documentation: If there are recommended patterns or constraints for UIScene + Impeller on iOS (e.g. when to trigger layout, or how to avoid this scenario), documenting them would help.

Related issues / PRs (if any)

• flutter/engine#19592 – Create surface in viewDidLayoutSubviews only when app is active.
• flutter/engine#169378 – Impeller iOS image decoding and command buffer scheduling when backgrounded.
• flutter/engine#39359 – FlutterView background and CAMetalLayer nextDrawable.
• General “white screen after long background” reports: e.g. Flutter issue App is showing white screen after few hours of running in background. #82969, Images are not rendered after application resumes from background #64558 (similar symptoms on iOS/Android).

Checklist

• I have read the contributing guide.
• I have searched existing issues and discussions; this appears to be a known class of problem but we are providing a concrete repro and environment.
• I am willing to provide more logs or a minimal repro if requested.

[mbcorona]

Thanks for the investigation into the Metal surface lifecycle, @kwongfung.
I am routing this to the engine team for evaluation.

[gaaclarke]

@mbcorona were you able to reproduce this? It would be interesting to know if there is something unique in this setup that causes this or if we could get it with the counter app.

[mbcorona]

@gaaclarke I actually did not reproduce this locally. I applied the has reproducible steps label based on the details of the author's repro steps, logs, and root-cause analysis, as this type of long-background memory-pressure bug is difficult to trigger reliably in a standard triage environment.

@kwongfung To help the engine team narrow this down, are you able to trigger this behavior using a brand-new flutter create counter app left in the background, or does it only happen in your production app with its specific memory footprint?

[kwongfung]

I am not able to trigger this behavior using a brand-new flutter create counter app left in the background.
we use flutter_screen_ratio_adapter in our app，I think there is something going wrong?

[gaaclarke]

I looked through flutter_screen_ratio_adapter and nothing jumped out at me. You should try finding the minimal amount of code required to reproduce your problem. For example, if you think it's related to flutter_screen_ratio_adapter, try to adapt that into the flutter counter app and see if you can reproduce it.