Repository navigation
Flutter macOS desktop app freezes after switching applications using Mission Control. #155977
Description
Steps to reproduce
- Create a new Flutter project: flutter create bug.
- Run the application and switch to another app. Then, reopen the Flutter app using Mission Control.
- Try this multiple times—you will likely encounter the issue within one or two tries. Also, check out the video I’ve provided, where I’ve recreated the issue. Interestingly, when I maximize the app from the bottom icons, it works fine.
Expected results
App should not freeze if app opens from Mission Control.
Actual results
App becomes not responding when it opens from mission control.
Same bug reported on windows but i have tested on windows it works fine. #74797
Code sample
import 'package:flutter/material.dart';
void main() {
runApp(const MyApp());
}
class MyApp extends StatelessWidget {
const MyApp({super.key});
// This widget is the root of your application.
@override
Widget build(BuildContext context) {
return MaterialApp(
title: 'Flutter Demo',
theme: ThemeData(
// This is the theme of your application.
//
// TRY THIS: Try running your application with "flutter run". You'll see
// the application has a purple toolbar. Then, without quitting the app,
// try changing the seedColor in the colorScheme below to Colors.green
// and then invoke "hot reload" (save your changes or press the "hot
// reload" button in a Flutter-supported IDE, or press "r" if you used
// the command line to start the app).
//
// Notice that the counter didn't reset back to zero; the application
// state is not lost during the reload. To reset the state, use hot
// restart instead.
//
// This works for code too, not just values: Most code changes can be
// tested with just a hot reload.
colorScheme: ColorScheme.fromSeed(seedColor: Colors.deepPurple),
useMaterial3: true,
),
home: const MyHomePage(title: 'Flutter Demo Home Page'),
);
}
}
class MyHomePage extends StatefulWidget {
const MyHomePage({super.key, required this.title});
// This widget is the home page of your application. It is stateful, meaning
// that it has a State object (defined below) that contains fields that affect
// how it looks.
// This class is the configuration for the state. It holds the values (in this
// case the title) provided by the parent (in this case the App widget) and
// used by the build method of the State. Fields in a Widget subclass are
// always marked "final".
final String title;
@override
State<MyHomePage> createState() => _MyHomePageState();
}
class _MyHomePageState extends State<MyHomePage> {
int _counter = 0;
void _incrementCounter() {
setState(() {
// This call to setState tells the Flutter framework that something has
// changed in this State, which causes it to rerun the build method below
// so that the display can reflect the updated values. If we changed
// _counter without calling setState(), then the build method would not be
// called again, and so nothing would appear to happen.
_counter++;
});
}
@override
Widget build(BuildContext context) {
// This method is rerun every time setState is called, for instance as done
// by the _incrementCounter method above.
//
// The Flutter framework has been optimized to make rerunning build methods
// fast, so that you can just rebuild anything that needs updating rather
// than having to individually change instances of widgets.
return Scaffold(
appBar: AppBar(
// TRY THIS: Try changing the color here to a specific color (to
// Colors.amber, perhaps?) and trigger a hot reload to see the AppBar
// change color while the other colors stay the same.
backgroundColor: Theme.of(context).colorScheme.inversePrimary,
// Here we take the value from the MyHomePage object that was created by
// the App.build method, and use it to set our appbar title.
title: Text(widget.title),
),
body: Center(
// Center is a layout widget. It takes a single child and positions it
// in the middle of the parent.
child: Column(
// Column is also a layout widget. It takes a list of children and
// arranges them vertically. By default, it sizes itself to fit its
// children horizontally, and tries to be as tall as its parent.
//
// Column has various properties to control how it sizes itself and
// how it positions its children. Here we use mainAxisAlignment to
// center the children vertically; the main axis here is the vertical
// axis because Columns are vertical (the cross axis would be
// horizontal).
//
// TRY THIS: Invoke "debug painting" (choose the "Toggle Debug Paint"
// action in the IDE, or press "p" in the console), to see the
// wireframe for each widget.
mainAxisAlignment: MainAxisAlignment.center,
children: <Widget>[
const Text(
'You have pushed the button this many times:',
),
Text(
'$_counter',
style: Theme.of(context).textTheme.headlineMedium,
),
],
),
),
floatingActionButton: FloatingActionButton(
onPressed: _incrementCounter,
tooltip: 'Increment',
child: const Icon(Icons.add),
), // This trailing comma makes auto-formatting nicer for build methods.
);
}
}
Screenshots or Video
Screenshots / Video demonstration
Screen.Recording.2024-10-01.at.7.47.28.AM.mp4
Logs
Logs
[Paste your logs here]Flutter Doctor output
Doctor output
kirshi@Kirshis-MacBook-Pro ~ % flutter doctor -v
[✓] Flutter (Channel stable, 3.24.3, on macOS 15.0 24A335 darwin-x64, locale
en-US)
• Flutter version 3.24.3 on channel stable at
/Users/kirshi/Development/flutter
• Upstream repository https://github.com/flutter/flutter.git
• Framework revision 2663184aa7 (3 weeks ago), 2024-09-11 16:27:48 -0500
• Engine revision 36335019a8
• Dart version 3.5.3
• DevTools version 2.37.3
[!] Android toolchain - develop for Android devices (Android SDK version 34.0.0)
• Android SDK at /Users/kirshi/Library/Android/sdk
✗ cmdline-tools component is missing
Run `path/to/sdkmanager --install "cmdline-tools;latest"`
See https://developer.android.com/studio/command-line for more details.
✗ Android license status unknown.
Run `flutter doctor --android-licenses` to accept the SDK licenses.
See https://flutter.dev/to/macos-android-setup for more details.
[✓] Xcode - develop for iOS and macOS (Xcode 16.0)
• Xcode at /Applications/Xcode.app/Contents/Developer
• Build 16A242d
• CocoaPods version 1.15.2
[✗] Chrome - develop for the web (Cannot find Chrome executable at
/Applications/Google Chrome.app/Contents/MacOS/Google Chrome)
! Cannot find Chrome. Try setting CHROME_EXECUTABLE to a Chrome executable.
[✓] Android Studio (version 2024.1)
• Android Studio at /Applications/Android Studio.app/Contents
• Flutter plugin can be installed from:
🔨 https://plugins.jetbrains.com/plugin/9212-flutter
• Dart plugin can be installed from:
🔨 https://plugins.jetbrains.com/plugin/6351-dart
• Java version OpenJDK Runtime Environment (build
17.0.11+0-17.0.11b1207.24-11852314)
[✓] VS Code (version 1.93.1)
• VS Code at /Applications/Visual Studio Code.app/Contents
• Flutter extension version 3.96.0
[✓] Connected device (1 available)
• macOS (desktop) • macos • darwin-x64 • macOS 15.0 24A335 darwin-x64
[✓] Network resources
• All expected network resources are available.
! Doctor found issues in 2 categories.
kirshi@Kirshis-MacBook-Pro ~ %
Reacted by Ravi Teja Gudapati and ellie-ya
Activity
darshankawar commentedon Oct 1, 2024
Thanks for the report @chitraarasu
I tried the same on my mac but wasn't able to replicate the reported behavior. I tried almost 10 to 15 times to be sure.
I used trackpad to bring up or use mission control key by swiping with four fingers on it. Are you also using trackpad or mouse ?
Also, can you check if it occurs with native macOS app as well (ex: notes) ?
I see that you are on latest macOS which I am not on, maybe that can be a factor as well.
Tedsterh commentedon Oct 1, 2024
Heya, I am also experiencing the same issue, specifically when I have the app running in a second desktop and I swipe between, the macOS app freezes and when I try to hot reload from vscode the app crashes and I have to rebuild it.
I have recently upgraded my flutter to version 3.24.3, here is my flutter doctor output as well:
chitraarasu commentedon Oct 1, 2024
Hi @darshankawar,
darshankawar commentedon Oct 2, 2024
Thanks for the update. I tried it again but was not able to replicate, but my colleague was able to replicate it once but not after that, so we can't be sure to provide a concrete pattern that leads to the reported behavior.
Colleague tried on macOS 15, while this observation was on macOS 14.6
flutter doctor -v (stable and master)
Since it seems to be intermittent, I will keep it open for team's tracking.
codesession81 commentedon Dec 28, 2024
Iam experiencing the same problem, running the latest OSX, flutter (stable channel) and XCode version.
When i switch between vscode and the app with mission controll the app freezes, hot reload or restart shows no effect.
I´ve tried debugging mode but get no errors or thrown exceptions.
It doesn`t matter if i run the default or a bigger project, in both cases the problem occours, so posting code seems to be useless.
Is there any workaround?
jerefrer commentedon Jan 20, 2025
I don't know if that's exactly the same thing, but I started debugging my app as macOS target, which worked fine until I decided to expand the app into its own space, then drag a browser with YouTube tutorial I was following on that space to have a split view. I think at first it worked, I could even move the vertical line to resize the spaces, but then I don't remember which actions I did and it just froze.
After that whenever I run the app it starts as full screen in its own space and is immediately frozen. I can't un-expand it back to the normal desktop nor do anything else.
Any idea what to do ?
Is there a place I could force the app to start as a normal window again, like forgetting its last state to return to defaults ?
Thanks !
Princewil commentedon Feb 13, 2025
ahmeedev commentedon Apr 1, 2025
belizariogr commentedon Aug 28, 2025
Jishnu-p-ibo commentedon Sep 2, 2025
xiaofeifei-sudo commentedon Jan 28, 2026
My computer, after being asleep for a long time, also experiences freezing when restarting applications.
ellie-ka-nam commentedon Jun 26, 2026
Additional reproduction + detailed diagnostics (macOS render freeze after occlusion)
We are hitting this on a production macOS Flutter app and did fairly deep debugging. Sharing in case it helps narrow the root cause.
Environment
WKWebView(viaflutter_inappwebview) on the main screen, but the issue is not webview-specific (see below)Symptom
Key differentiators we found
open(LaunchServices GUI launch) → freezes. Running the same binary directly from Terminal (Foo.app/Contents/MacOS/Foo) → never freezes, no matter how many times we switch away/back.What the freeze looks like in a
sample(spindump-style)At the moment of freeze, every thread is idle/parked — there is no busy/spinning thread and nothing blocked on a lock:
main thread: parked in-[NSApplication run]→_DPSNextEvent→mach_msg2_trap(normal idle event loop)io.flutter.ui: parked inCFRunLoopRunSpecific→__CFRunLoopRun→mach_msg(waiting for a vsync wakeup that never comes)io.flutter.raster: parked inCFRunLoopRunSpecific→mach_msg— not in[CAMetalLayer nextDrawable], not in any semaphore wait__psynch_cvwaitSo it is not a deadlock and not a
nextDrawable/GPU stall — it looks exactly like frame production / the display-link vsync simply stops being driven and never resumes after the occlusion→visible transition. The Dart isolate is alive (we caught it mid-execution in some samples), it's just never ticked for a new frame.Things we tried that did NOT fix it (all confirmed active in the tested build via logging):
ProcessInfo.beginActivity(.userInitiatedAllowingIdleSystemSleep), alsoNSAppSleepDisabled) — no effect.FLTEnableMergedPlatformUIThread=false) — confirmed off (separateio.flutter.uithread appears), still freezes.WidgetsBinding.instance.scheduleForcedFrame()on resume — no effect (the display link is the gate; forcing a frame request doesn't restart it).NSWindow.didChangeOcclusionStateNotification"became visible" transition:setNeedsDisplay+ a 1px window resize,makeKeyAndOrderFront+orderFrontRegardless, and evenorderOut(nil)followed bymakeKeyAndOrderFront(programmatically re-showing the window) — none recover rendering, even though a real user Dock-click (which is the same conceptual "re-show") does.The fact that a genuine Dock-click recovers it but no programmatic
orderOut/orderFront/makeKeyAndOrderFrontdoes, suggests the recovery requires a real WindowServer-driven occlusion/visibility event that the engine observes to restart the display link — and the normal Cmd-Tab/Mission-Control return path is not delivering whatever signal the engine needs to resume frame production.Notes
applicationDidBecomeActivedoes not fire on these app-switch transitions for us (the app does not fully resign/become active on occlusion), so any workaround hooked there is dead code.NSWindow.didChangeOcclusionStateNotificationdoes fire reliably.sampleoutputs for the frozen state if useful.ellie-ka-nam commentedon Jun 30, 2026
Update: root cause found, and a fix PR is up → #188772
Following up on my earlier comment. I built a local engine with tracing in
FlutterEngine(app-lifecycle) plusFlutterVSyncWaiter/FlutterDisplayLink(vsync) and reproduced the freeze on a low-spec Intel Mac. The trace showed the vsync/display-link layer is actually healthy — my earlier "the display link stops and never resumes" reading was a symptom, not the cause. The engine simply was never asked to render, because the framework had been told it was hidden.Root cause is in
FlutterEngine's lifecycle handling:_visibleis updated only byhandleDidChangeOcclusionState. macOS does not reliably deliver anNSApplicationDidChangeOcclusionState(visible) notification on every occlusion→visible transition — returning to the app on the same screen (Cmd-Tab / Mission Control / clicking away and back) frequently deliversvisible=NOwhen leaving but never deliversvisible=YESwhen returning. So:kHidden,_visible = NO(frames disabled — correct).applicationWillBecomeActivefires, but_visibleis still stale-NO, sokHiddenis sent again.scheduleFramegated, no vsync requested → frozen UI even though the window is on-screen and frontmost.The trace at the freezing return:
i.e.
willBecomeActivedoes fire on the return, but[[NSApplication sharedApplication] occlusionState]still reads not-visible at that instant and thevisiblenotification never arrives. This also explains the earlier observations: programmaticorderFront/makeKeyAndOrderFrontdidn't help (they don't update the lifecycle), while a real Dock-icon activation did (it eventually drives the occlusion state back to visible). Terminal-launched processes don't hit the aggressive occlusion behavior, so they never freeze.Fix (in #188772): an app receiving
applicationWillBecomeActiveis frontmost and visible, so treat that as an authoritative "visible" signal and resume.handleDidChangeOcclusionStatestill driveskHiddenwhen genuinely occluded, so the app can still go hidden.Verified on the Intel repro with a custom engine build: with this change the UI keeps rendering across every occlusion→return cycle. PR includes a regression test in
FlutterEngineTest.mm.Workaround until it lands in a stable release: when frozen, click the app's Dock icon to bring it back (rather than Cmd-Tab / Mission Control).
cbracken commentedon Aug 3, 2026
If I'm understanding correctly, this was introduced in flutter-team-archive/engine#40542, reverted in flutter-team-archive/engine#42384, relanded in flutter-team-archive/engine#42418. In the original code
_visibleis only ever updated by the occlusion notification andhandleWillBecomeActiverelies on that.That code dates back to 2023; looks like this was reported about a year and a little after so that tracks. @ellie-ka-nam thanks for the excellent analysis and the fix.
[macOS] Resume app lifecycle on becomeActive to avoid frozen UI after…
[cp-beta] [macOS] Resume app lifecycle on becomeActive to avoid froze…
github-actions commentedon Aug 17, 2026
This thread has been automatically locked since there has not been any recent activity after it was closed. If you are still experiencing a similar issue, please open a new bug, including the output of
flutter doctor -vand a minimal reproduction of the issue.