Skip to content

Flutter GPU must be enabled via the Flutter GPU manifest setting #168126

Closed

Description

@eskov-ea

Steps to reproduce

I'm trying to run example with Flutter GPU at https://medium.com/flutter/getting-started-with-flutter-gpu-f33d497b7c11

flutter channel master
flutter upgrade
flutter pub add flutter_gpu --sdk=flutter
flutter pub add flutter_gpu_shaders
flutter config --enable-native-assets
flutter pub add native_assets_cli
flutter run -d macos --enable-impeller

I tried to add suggested argument --enable-flutter-gpu to be attached to a device via edit configuration

Expected results

I expect the code to compile and executes with no crash as the tutorial says.

Actual results

Crash at runtime with the following output:

The following _Exception was thrown during paint():
Exception: Flutter GPU must be enabled via the Flutter GPU manifest setting. This can be done either via command line argument --enable-flutter-gpu or by adding the FLTEnableFlutterGPU key set to true on iOS or io.flutter.embedding.android.EnableFlutterGPU metadata key to true on Android.

Code sample

Code sample
[Paste your code here]

Screenshots or Video

Screenshots / Video demonstration

[Upload media here]

Logs

Logs
Launching lib/main.dart on macOS in debug mode...
Building macOS application...
--- xcodebuild: WARNING: Using the first of multiple matching destinations:
{ platform:macOS, arch:arm64, id:00006000-000470242262801E, name:My Mac }
{ platform:macOS, arch:x86_64, id:00006000-000470242262801E, name:My Mac }
✓ Built build/macos/Build/Products/Debug/gpu_test.app
2025-05-01 13:32:57.660 gpu_test[68323:22319671] Running with merged UI and platform thread. Experimental.
[IMPORTANT:flutter/shell/platform/embedder/embedder_surface_metal_impeller.mm(51)] Using the Impeller rendering backend (Metal).
Failed to foreground app; open returned 1
Debug service listening on ws://127.0.0.1:65135/JOuKpAuh00o=/ws
Syncing files to device macOS...
2025-05-01 13:32:58.187 gpu_test[68323:22319671] +[IMKClient subclass]: chose IMKClient_Modern
2025-05-01 13:32:58.187 gpu_test[68323:22319671] +[IMKInputSession subclass]: chose IMKInputSession_Modern

======== Exception caught by rendering library =====================================================
The following _Exception was thrown during paint():
Exception: Flutter GPU must be enabled via the Flutter GPU manifest setting. This can be done either via command line argument --enable-flutter-gpu or by adding the FLTEnableFlutterGPU key set to true on iOS or io.flutter.embedding.android.EnableFlutterGPU metadata key to true on Android.

The relevant error-causing widget was: 
  CustomPaint CustomPaint:file:///Users/evgeny/Practice/flutter/gpu_test/lib/main.dart:20:13
When the exception was thrown, this was the stack: 
#0      new GpuContext._createDefault (package:flutter_gpu/src/context.dart:18:7)
#1      gpuContext (package:flutter_gpu/src/context.dart:187:42)
#2      gpuContext (package:flutter_gpu/src/context.dart)
#3      TrianglePainter.paint (package:gpu_test/main.dart:33:13)
#4      RenderCustomPaint._paintWithPainter (package:flutter/src/rendering/custom_paint.dart:593:13)
#5      RenderCustomPaint.paint (package:flutter/src/rendering/custom_paint.dart:641:7)
#6      RenderObject._paintWithContext (package:flutter/src/rendering/object.dart:3483:7)
#7      PaintingContext.paintChild (package:flutter/src/rendering/object.dart:261:13)
#8      RenderProxyBoxMixin.paint (package:flutter/src/rendering/proxy_box.dart:140:13)
#9      RenderObject._paintWithContext (package:flutter/src/rendering/object.dart:3483:7)
#10     PaintingContext.paintChild (package:flutter/src/rendering/object.dart:261:13)
#11     RenderProxyBoxMixin.paint (package:flutter/src/rendering/proxy_box.dart:140:13)
#12     RenderObject._paintWithContext (package:flutter/src/rendering/object.dart:3483:7)
#13     PaintingContext._repaintCompositedChild (package:flutter/src/rendering/object.dart:176:11)
#14     PaintingContext.repaintCompositedChild (package:flutter/src/rendering/object.dart:121:5)
#15     PaintingContext._compositeChild (package:flutter/src/rendering/object.dart:272:7)
#16     PaintingContext.paintChild (package:flutter/src/rendering/object.dart:253:7)
#17     RenderProxyBoxMixin.paint (package:flutter/src/rendering/proxy_box.dart:140:13)
#18     RenderObject._paintWithContext (package:flutter/src/rendering/object.dart:3483:7)
#19     PaintingContext.paintChild (package:flutter/src/rendering/object.dart:261:13)
#20     RenderBoxContainerDefaultsMixin.defaultPaint (package:flutter/src/rendering/box.dart:3372:15)
#21     RenderStack.paintStack (package:flutter/src/rendering/stack.dart:704:5)
#22     RenderStack.paint (package:flutter/src/rendering/stack.dart:720:7)
#23     RenderObject._paintWithContext (package:flutter/src/rendering/object.dart:3483:7)
#24     PaintingContext.paintChild (package:flutter/src/rendering/object.dart:261:13)
#25     RenderProxyBoxMixin.paint (package:flutter/src/rendering/proxy_box.dart:140:13)
#26     RenderDecoratedBox.paint (package:flutter/src/rendering/proxy_box.dart:2450:11)
#27     RenderObject._paintWithContext (package:flutter/src/rendering/object.dart:3483:7)
#28     PaintingContext.paintChild (package:flutter/src/rendering/object.dart:261:13)
#29     RenderProxyBoxMixin.paint (package:flutter/src/rendering/proxy_box.dart:140:13)
#30     RenderFractionalTranslation.paint (package:flutter/src/rendering/proxy_box.dart:3072:13)
#31     RenderObject._paintWithContext (package:flutter/src/rendering/object.dart:3483:7)
#32     PaintingContext.paintChild (package:flutter/src/rendering/object.dart:261:13)
#33     RenderProxyBoxMixin.paint (package:flutter/src/rendering/proxy_box.dart:140:13)
#34     RenderFractionalTranslation.paint (package:flutter/src/rendering/proxy_box.dart:3072:13)
#35     RenderObject._paintWithContext (package:flutter/src/rendering/object.dart:3483:7)
#36     PaintingContext.paintChild (package:flutter/src/rendering/object.dart:261:13)
#37     RenderProxyBoxMixin.paint (package:flutter/src/rendering/proxy_box.dart:140:13)
#38     RenderObject._paintWithContext (package:flutter/src/rendering/object.dart:3483:7)
#39     PaintingContext._repaintCompositedChild (package:flutter/src/rendering/object.dart:176:11)
#40     PaintingContext.repaintCompositedChild (package:flutter/src/rendering/object.dart:121:5)
#41     PaintingContext._compositeChild (package:flutter/src/rendering/object.dart:272:7)
#42     PaintingContext.paintChild (package:flutter/src/rendering/object.dart:253:7)
#43     RenderProxyBoxMixin.paint (package:flutter/src/rendering/proxy_box.dart:140:13)
#44     RenderObject._paintWithContext (package:flutter/src/rendering/object.dart:3483:7)
#45     PaintingContext.paintChild (package:flutter/src/rendering/object.dart:261:13)
#46     RenderProxyBoxMixin.paint (package:flutter/src/rendering/proxy_box.dart:140:13)
#47     RenderOffstage.paint (package:flutter/src/rendering/proxy_box.dart:3877:11)
#48     RenderObject._paintWithContext (package:flutter/src/rendering/object.dart:3483:7)
#49     PaintingContext.paintChild (package:flutter/src/rendering/object.dart:261:13)
#50     RenderProxyBoxMixin.paint (package:flutter/src/rendering/proxy_box.dart:140:13)
#51     RenderObject._paintWithContext (package:flutter/src/rendering/object.dart:3483:7)
#52     PaintingContext.paintChild (package:flutter/src/rendering/object.dart:261:13)
#53     _RenderTheaterMixin.paint (package:flutter/src/widgets/overlay.dart:1120:15)
#54     _RenderTheater.paint (package:flutter/src/widgets/overlay.dart:1478:13)
#55     RenderObject._paintWithContext (package:flutter/src/rendering/object.dart:3483:7)
#56     PaintingContext.paintChild (package:flutter/src/rendering/object.dart:261:13)
#57     RenderProxyBoxMixin.paint (package:flutter/src/rendering/proxy_box.dart:140:13)
#58     RenderObject._paintWithContext (package:flutter/src/rendering/object.dart:3483:7)
#59     PaintingContext.paintChild (package:flutter/src/rendering/object.dart:261:13)
#60     RenderProxyBoxMixin.paint (package:flutter/src/rendering/proxy_box.dart:140:13)
#61     RenderObject._paintWithContext (package:flutter/src/rendering/object.dart:3483:7)
#62     PaintingContext.paintChild (package:flutter/src/rendering/object.dart:261:13)
#63     RenderProxyBoxMixin.paint (package:flutter/src/rendering/proxy_box.dart:140:13)
#64     RenderObject._paintWithContext (package:flutter/src/rendering/object.dart:3483:7)
#65     PaintingContext.paintChild (package:flutter/src/rendering/object.dart:261:13)
#66     RenderProxyBoxMixin.paint (package:flutter/src/rendering/proxy_box.dart:140:13)
#67     RenderCustomPaint.paint (package:flutter/src/rendering/custom_paint.dart:644:11)
#68     RenderObject._paintWithContext (package:flutter/src/rendering/object.dart:3483:7)
#69     PaintingContext.paintChild (package:flutter/src/rendering/object.dart:261:13)
#70     RenderProxyBoxMixin.paint (package:flutter/src/rendering/proxy_box.dart:140:13)
#71     RenderObject._paintWithContext (package:flutter/src/rendering/object.dart:3483:7)
#72     PaintingContext.paintChild (package:flutter/src/rendering/object.dart:261:13)
#73     RenderProxyBoxMixin.paint (package:flutter/src/rendering/proxy_box.dart:140:13)
#74     RenderObject._paintWithContext (package:flutter/src/rendering/object.dart:3483:7)
#75     PaintingContext.paintChild (package:flutter/src/rendering/object.dart:261:13)
#76     RenderProxyBoxMixin.paint (package:flutter/src/rendering/proxy_box.dart:140:13)
#77     RenderObject._paintWithContext (package:flutter/src/rendering/object.dart:3483:7)
#78     PaintingContext.paintChild (package:flutter/src/rendering/object.dart:261:13)
#79     RenderProxyBoxMixin.paint (package:flutter/src/rendering/proxy_box.dart:140:13)
#80     RenderObject._paintWithContext (package:flutter/src/rendering/object.dart:3483:7)
#81     PaintingContext.paintChild (package:flutter/src/rendering/object.dart:261:13)
#82     RenderProxyBoxMixin.paint (package:flutter/src/rendering/proxy_box.dart:140:13)
#83     RenderObject._paintWithContext (package:flutter/src/rendering/object.dart:3483:7)
#84     PaintingContext.paintChild (package:flutter/src/rendering/object.dart:261:13)
#85     RenderProxyBoxMixin.paint (package:flutter/src/rendering/proxy_box.dart:140:13)
#86     RenderObject._paintWithContext (package:flutter/src/rendering/object.dart:3483:7)
#87     PaintingContext.paintChild (package:flutter/src/rendering/object.dart:261:13)
#88     RenderProxyBoxMixin.paint (package:flutter/src/rendering/proxy_box.dart:140:13)
#89     RenderObject._paintWithContext (package:flutter/src/rendering/object.dart:3483:7)
#90     PaintingContext.paintChild (package:flutter/src/rendering/object.dart:261:13)
#91     RenderView.paint (package:flutter/src/rendering/view.dart:322:15)
#92     RenderObject._paintWithContext (package:flutter/src/rendering/object.dart:3483:7)
#93     PaintingContext._repaintCompositedChild (package:flutter/src/rendering/object.dart:176:11)
#94     PaintingContext.repaintCompositedChild (package:flutter/src/rendering/object.dart:121:5)
#95     PipelineOwner.flushPaint (package:flutter/src/rendering/object.dart:1312:31)
#96     PipelineOwner.flushPaint (package:flutter/src/rendering/object.dart:1322:15)
#97     RendererBinding.drawFrame (package:flutter/src/rendering/binding.dart:631:23)
#98     WidgetsBinding.drawFrame (package:flutter/src/widgets/binding.dart:1231:13)
#99     RendererBinding._handlePersistentFrameCallback (package:flutter/src/rendering/binding.dart:495:5)
#100    SchedulerBinding._invokeFrameCallback (package:flutter/src/scheduler/binding.dart:1438:15)
#101    SchedulerBinding.handleDrawFrame (package:flutter/src/scheduler/binding.dart:1351:9)
#102    SchedulerBinding.scheduleWarmUpFrame.<anonymous closure> (package:flutter/src/scheduler/binding.dart:1060:9)
#103    PlatformDispatcher.scheduleWarmUpFrame.<anonymous closure> (dart:ui/platform_dispatcher.dart:889:16)
#107    _RawReceivePort._handleMessage (dart:isolate-patch/isolate_patch.dart:193:12)
(elided 3 frames from class _Timer and dart:async-patch)
The following RenderObject was being processed when the exception was fired: RenderCustomPaint#40a03
...  parentData: <none> (can use size)
...  constraints: BoxConstraints(w=800.0, h=600.0)
...  size: Size(800.0, 600.0)
...  painter: TrianglePainter#e40bf()
RenderObject: RenderCustomPaint#40a03
  parentData: <none> (can use size)
  constraints: BoxConstraints(w=800.0, h=600.0)
  size: Size(800.0, 600.0)
  painter: TrianglePainter#e40bf()
====================================================================================================

Flutter Doctor output

Doctor output
evgeny@MacBook-Pro-admin gpu_test % flutter doctor -v
[✓] Flutter (Channel main, 3.32.0-1.0.pre.343, on macOS 15.1 24B83 darwin-arm64, locale ru-RU) [14,6s]
    • Flutter version 3.32.0-1.0.pre.343 on channel main at /Users/evgeny/Documents/services/flutter-main
    • Upstream repository https://github.com/flutter/flutter.git
    • Framework revision 87753f3840 (4 hours ago), 2025-04-30 19:55:04 -0400
    • Engine revision 87753f3840
    • Dart version 3.9.0 (build 3.9.0-63.0.dev)
    • DevTools version 2.45.0

[✓] Android toolchain - develop for Android devices (Android SDK version 35.0.0) [3,7s]
    • Android SDK at /Users/evgeny/Library/Android/sdk
    • Emulator version 35.2.10.0 (build_id 12414864) (CL:N/A)
    • Platform android-35, build-tools 35.0.0
    • Java binary at: /Users/evgeny/Library/Java/JavaVirtualMachines/jbr-17.0.12/Contents/Home/bin/java
      This JDK is specified in your Flutter configuration.
      To change the current JDK, run: `flutter config --jdk-dir="path/to/jdk"`.
    • Java version OpenJDK Runtime Environment JBR-17.0.12+1-1207.37-nomod (build 17.0.12+1-b1207.37)
    • All Android licenses accepted.

[✓] Xcode - develop for iOS and macOS (Xcode 16.2) [1 055ms]
    • Xcode at /Applications/Xcode.app/Contents/Developer
    • Build 16C5032a
    • CocoaPods version 1.16.2

[✓] Chrome - develop for the web [12ms]
    • Chrome at /Applications/Google Chrome.app/Contents/MacOS/Google Chrome

[✓] Android Studio (version 2024.2) [11ms]
    • 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 21.0.3+-79915917-b509.11)

[✓] VS Code (version 1.99.3) [10ms]
    • VS Code at /Applications/Visual Studio Code.app/Contents
    • Flutter extension can be installed from:
      🔨 https://marketplace.visualstudio.com/items?itemName=Dart-Code.flutter

[✓] Connected device (2 available) [6,0s]
    • macOS (desktop) • macos  • darwin-arm64   • macOS 15.1 24B83 darwin-arm64
    • Chrome (web)    • chrome • web-javascript • Google Chrome 135.0.7049.115
    ! Error: Browsing on the local area network for iPhone  Евгений. Ensure the device is unlocked and attached with a cable or associated with the same local
      area network as this Mac.
      The device must be opted into Developer Mode to connect wirelessly. (code -27)

[✓] Network resources [1 363ms]
    • All expected network resources are available.

Activity

  1. changed the title [-][Impeller] Flutter GPU must be enabled via the Flutter GPU manifest setting[/-] [+]Flutter GPU must be enabled via the Flutter GPU manifest setting[/+] on May 1, 2025
  2. darshankawar commented on May 2, 2025

    @darshankawar
    Member

    @eskov-ea
    I tried the same with latest master version and running on mac using a demo app and I didn't get the reported behavior:

    dhs@Dhss-MacBook-Pro flutter_issue % flutter run -d macos --enable-impeller
    Resolving dependencies... 
    Downloading packages... 
      archive 4.0.5 (4.0.7 available)
      flutter_plugin_android_lifecycle 2.0.27 (2.0.28 available)
      flutter_svg 2.0.17 (2.1.0 available)
      google_maps_flutter_android 2.16.0 (2.16.1 available)
      google_maps_flutter_ios 2.15.1 (2.15.2 available)
      html 0.15.5 (0.15.6 available)
      interactive_media_ads 0.2.3+10 (0.2.3+11 available)
      lints 5.1.1 (6.0.0 available)
      material_color_utilities 0.11.1 (0.12.0 available)
      native_assets_cli 0.13.0 (discontinued replaced by hooks)
      posix 6.0.1 (6.0.2 available)
      vector_math 2.1.4 (2.1.5 available)
      video_player_avfoundation 2.7.0 (2.7.1 available)
      video_player_web 2.3.4 (2.3.5 available)
      webview_flutter 4.10.0 (4.11.0 available)
      webview_flutter_android 4.3.4 (4.4.2 available)
      webview_flutter_platform_interface 2.10.0 (2.11.0 available)
      webview_flutter_wkwebview 3.18.5 (3.20.0 available)
    Got dependencies!
    1 package is discontinued.
    18 packages have newer versions incompatible with dependency constraints.
    Try `flutter pub outdated` for more information.
    Launching lib/main.dart on macOS in debug mode...
    Updating minimum macOS deployment target to 10.15.
    Upgrading project.pbxproj
    Building macOS application...                                           
    ✓ Built build/storybook/macos/Build/Products/Debug/flutter_issue.app
    2025-05-02 14:02:29.988 flutter_issue[3718:131864] Running with merged UI and platform thread. Experimental.
    [IMPORTANT:flutter/shell/platform/embedder/embedder_surface_metal_impeller.mm(51)] Using the Impeller rendering backend (Metal).
    Failed to foreground app; open returned 1
    Syncing files to device macOS...                                    92ms
    
    Flutter run key commands.
    r Hot reload. 🔥🔥🔥
    R Hot restart.
    h List all available interactive commands.
    d Detach (terminate "flutter run" but leave application running).
    c Clear the screen
    q Quit (terminate the application on the device).
    
    A Dart VM Service on macOS is available at: http://127.0.0.1:50738/_6S1pzPXsRQ=/
    The Flutter DevTools debugger and profiler on macOS is available at:
    http://127.0.0.1:9100?uri=http://127.0.0.1:50738/_6S1pzPXsRQ=/
    2025-05-02 14:02:31.947 flutter_issue[3718:131864] +[IMKClient subclass]: chose IMKClient_Modern
    2025-05-02 14:02:31.947 flutter_issue[3718:131864] +[IMKInputSession subclass]: chose IMKInputSession_Modern
    
    

    Based on the error log shared, it seems to be similar to #167734

    /cc @jonahwilliams for thoughts if this need to be tracked separately ?

  3. added
    waiting for responseThe Flutter team cannot make further progress on this issue until the original reporter responds
    on May 2, 2025
  4. eskov-ea commented on May 23, 2025

    @eskov-ea
    Author

    @darshankawar Hi, thanks for the answer. What macbook do you use?
    I ran this example on M2 and I will try to do it on M3 later, don't know what can happen.

    I also created a verbose log file with the 'flutter run' output.

    log.txt

  5. removed
    waiting for responseThe Flutter team cannot make further progress on this issue until the original reporter responds
    on May 23, 2025
  6. darshankawar commented on May 23, 2025

    @darshankawar
    Member

    What macbook do you use?

    I have Intel mac.

    Based on the error, I'll keep the issue open for team's tracking.

  7. added
    engineflutter/engine related. See also e: labels.
    platform-macosBuilding on or for macOS specifically
    and removed
    in triagePresently being triaged by the triage team
    on May 23, 2025
  8. moved this to 🤔 Needs Triage in Flutter GPUon May 23, 2025
  9. 1 remaining item

  10. lucas-goldner commented on Jun 5, 2025

    @lucas-goldner
    Contributor

    How do I enable --enable-flutter-gpu on macOS?

    I tried running the flutter scene demo on macOS with:

    flutter run -d macos --enable-impeller --enable-flutter-gpu
    

    but I keep getting

    Could not find an option named "--enable-flutter-gpu".
    Unlike iOS, even if I set the FLTEnableFlutterGPU key to true in the Info.plist, the macOS behaviour does not change.
    
  11. greensopinion commented on Jun 21, 2025

    @greensopinion

    Theory: A quick code search makes me think that something's missing for macOS and CLI switches on any platform: https://github.com/search?q=repo%3Aflutter%2Fflutter%20enable_flutter_gpu&type=code

    1. There is no MacOS equivalent in Flutter for this iOS bundle setting:
      NSNumber* enableFlutterGPU = [mainBundle objectForInfoDictionaryKey:@"FLTEnableFlutterGPU"];
    2. The CLI switch, used in switches.cc can never work because the allowed flags doesn't contain enable-flutter-gpu

    I haven't verified this theory

  12. self-assigned this
    on Jun 30, 2025
  13. moved this from 🤔 Needs Triage to ⚙️ In Progress in Flutter GPUon Jun 30, 2025
  14. moved this from ⚙️ In Progress to ✅ Done in Flutter GPUon Jul 1, 2025
  15. added
    r: fixedIssue is closed as already fixed in a newer version
    on Jul 2, 2025
  16. github-actions commented on Jul 16, 2025

    @github-actions

    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 -v and a minimal reproduction of the issue.

  17. locked as resolved and limited conversation to collaborators on Jul 16, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

P3Issues that are less important to the Flutter projectengineflutter/engine related. See also e: labels.flutter-gpuplatform-macosBuilding on or for macOS specificallyr: fixedIssue is closed as already fixed in a newer versionteam-engineOwned by Engine teamtriaged-engineTriaged by Engine team

Type

No type

Projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions