Skip to content

fix: stop the macOS app crashing in the background - #4

Merged
AbdurahmanAlmehdi merged 1 commit into
mainfrom
fix/macos-background-crash
Oct 17, 2026
Merged

AbdurahmanAlmehdi merged 1 commit into
mainfrom
fix/macos-background-crash

Conversation

@AbdurahmanAlmehdi

Copy link
Copy Markdown
Owner

Problem

XPath 1.0.0 (54) crashed on macOS 26.7.1 while it was in the background: EXC_BAD_ACCESS at 0x0 on io.flutter.raster, in impeller::Canvas::SetupRenderPass() (canvas.cc:1615), called from EmbedderExternalViewEmbedder::SubmitFlutterView.

Root cause: a Flutter engine bug

This is flutter/flutter#185394, "[Impeller] Crash on macOS when app is foregrounded" (open, P2, team-macos). The macOS back-buffer cache (FlutterBackBufferCache) can hand back a surface of the wrong size when the window's frame size changes and then changes back (A → B → A). Examples are a display hot-plug or reconfiguration, a Space or full-screen change, a window drag, or bringing the app to the front. Impeller wraps the mismatched MTLTexture, the texture invalidates itself, and the render target silently drops it. SetupRenderPass then dereferences the null texture.

  • Fix: flutter/flutter#192522 is still open (not merged). It is not in 3.47.7 (the latest stable, per its CHANGELOG) or in the 3.50 beta.
  • Also reported: #193095 (same stack) and #192829 (Cmd-Tab on macOS 27, closed as a duplicate).

Reproduced on our pinned SDK (3.47.6, release build). This used a minimal scratch app, not XPath. A Swift timer shrinks the window by 1 pt and restores it every 2.5 s, which is the driver from #192522. The Flutter side redraws a text once a second, the way XpClock does:

Renderer UI Result
Impeller (default) 1 s ticking text SIGSEGV after 5 s, at flip #1. The stack matches the field crash frame for frame (canvas.cc:1615 / 372, dl_dispatcher.cc:1318, embedder_external_view_embedder.cc:376 / 598).
Impeller still UI survived 60 s (17 flips)
Skia (FLTEnableImpeller=false) 1 s ticking text survived 90 s (36 flips), with no validation errors and the log line Using the Skia rendering backend (Metal).

Changes

  1. macos/Runner/Info.plist: FLTEnableImpeller = false (with a comment linking the issues). I checked the 3.47.6 engine source to confirm macOS still reads this key: FlutterDartProject.enableImpeller reads it, and FlutterEngine runWithEntrypoint then skips --enable-impeller=true and uses Skia (Metal). XPath uses no Impeller-only features (no fragment shaders, Flutter GPU or backdrop filters). Goldens and widget tests are unaffected because flutter test does not read Info.plist.
  2. XpClock follows the app lifecycle using an AppLifecycleListener. It ticks only while the app is resumed. When the app is inactive (visible but not in front), hidden (occluded or minimised) or paused, the timer stops. On resume, every live duration is rebuilt at once against the current time. The new XpClock.isLive(context) tells widgets whether the app is in front.
  3. XpSpinner stands still while !XpClock.isLive, as it already does under Reduce Motion.

Change 1 is the fix. Changes 2 and 3 mean XPath draws no frames of its own while it is not in front (it used to draw one a second for the clock, and 60 fps per spinner). That lowers the crash exposure and saves CPU and battery. On its own it does not fix the engine bug: a display change still causes a frame, and upstream reports idle apps crashing too.

Tests

apps/xp_desktop/test/widgets/xp_clock_test.dart drives the real flutter/lifecycle platform channel, the same messages the macOS embedder sends:

  • XpClock ticks every second while the app is in front
  • XpClock stops while inactive|hidden|paused and catches up on resume
  • XpClock a still clock stays still in front and away
  • XpClock starts still when the app is already away
  • XpClock without a clock above, the system time is live
  • XpClock spinners stand still while the app is away

Trade-offs and follow-ups

  • Skia is Flutter's legacy renderer on macOS. The Flutter docs warn that the Impeller opt-out will be removed in a future release, and with Skia there is no wide-gamut colour. Once a Flutter stable ships #192522, remove the key (the Info.plist comment says so).
  • While XPath is visible but not in front, elapsed times stay frozen until it comes back to the front, and then catch up at once.

Render with Skia instead of Impeller (FLTEnableImpeller=false): Impeller on macOS dereferences a null texture in Canvas::SetupRenderPass when the window's frame size flips (flutter/flutter#185394, fix pending in flutter/flutter#192522). The live clock and the spinners also stop while the app is not in front, so XPath draws no frames of its own in the background, and catch up on resume.
@cloudflare-workers-and-pages

Copy link
Copy Markdown

🚀 Deploying Preview to Cloudflare 🚀

Preview URL: https://fix-macos-background-crash-x-path.abdurahman-i-work.workers.dev (commit c02aabe)

This URL reflects your latest Preview deployment

Preview Deployments by commit

Status Deployment URL Commit Updated (UTC) See this deployment's details
  • Build: Success ✅
  • Deployment: Success ✅

View logs ↗
https://f4d1dd29-x-path.abdurahman-i-work.workers.dev c02aabe 2026-10-17T15:53:23.565Z Visit the dashboard ↗

@AbdurahmanAlmehdi
AbdurahmanAlmehdi merged commit 7880b86 into main Oct 17, 2026
5 checks passed
@AbdurahmanAlmehdi
AbdurahmanAlmehdi deleted the fix/macos-background-crash branch October 25, 2026 09:29
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant