Error when running a headless FlutterEngine in an iOS App Extension

Can a headless FlutterEngine work in iOS App Extensions? I'm trying to share Dart code between my main app and an iOS network extension via a Flutter module by loosely following Adding iOS app extensions and Integrate a Flutter module into iOS

When initializing the FlutterEngine and trying to invoke a MethodChannel in my Extension Service:

let engine = FlutterEngine(name: "extension", project: nil, allowHeadlessExecution: true)
engine.run(withEntrypoint: "main")*
// Create MethodChannel

I get this error:

Modifying properties of a view's layer off the main thread is not allowed: view <UIView: 0x104a57b80> with no associated or ancestor view controller;*

Is this architecture possible? The error suggests Flutter is still trying to create UI components despite running headless.

Addition Details

I have a large amount of Dart code that needs to be reused in my Push Provider Extension. A lot of it is pure Dart, so I can potentially at least reuse that using ffi(I think). But a good chunk uses Flutter as well (local notifications, audio, local storage). It would be awesome to reuse all of it in the iOS extension. I was hoping that running the FlutterEngine without the UI would create a smaller footprint and still allow access to the Flutter SDK. I really can't find any direct documentation around this.

@AlexNik4

@AlexNik4
Check if this maybe is related / similar to your case or not.

@darshankawar

@darshankawar Thanks for your response! Since the approach isn’t outright impossible, I tested further in a minimal sample project using a Packet Tunnel Network Extension (to avoid App Push Provider entitlement requirements). I ended up avoiding any additional plugins for now.

Current Setup in the Extension Service

FlutterEngine Initialization (Swift):
self.flutterEngine = FlutterEngine(  
    name: "extension_engine",  
    project: nil,  
    allowHeadlessExecution: true  
)  
flutterEngine.run(  
    withEntrypoint: "mainHeadless",  
    libraryURI: "package:flutter_ios_extension/headless.dart"

Confirmed the entrypoint is correct (misnamed withEntrypoint or libraryURI throw Dart_LookupLibrary errors).

headless.dart Entrypoint:

@pragma('vm:entry-point')  
void mainHeadless() {  
  WidgetsFlutterBinding.ensureInitialized();  
  const _channel = MethodChannel('com.example.flutterIosExtension/my_channel');  

  _channel.setMethodCallHandler((call) async {  
    switch (call.method) {  
      case 'getData':  
        return "Hello from Headless Flutter!";  
      default:  
        throw PlatformException(code: 'UNSUPPORTED_METHOD');  
    }  
  });  
  runApp(const SizedBox.shrink());  
}

Issues Observed

Still seeing the threading violation (despite no UI):

Modifying properties of a view's layer off the main thread is not allowed:  
view <UIView: 0x104a57b80> with no associated or ancestor view controller

Silent MethodChannel Failure:

methodChannel?.invokeMethod("getData", arguments: nil) { response in  
    NSLog("XXXX Received: \(response ?? "")")  // No output or errors  
}

The Dart handler is never triggered.

Any working examples of headless Flutter + MethodChannel in this context?
Any documentation on this use case?
I’d greatly appreciate any guidance—thanks again for your time!

Doctor summary (to see all details, run flutter doctor -v):
[✓] Flutter (Channel stable, 3.29.2, on macOS 15.3.2 24D81 darwin-arm64, locale en-US)
[✓] Android toolchain - develop for Android devices (Android SDK version 34.0.0)
[✓] Xcode - develop for iOS and macOS (Xcode 16.2)
[✓] Chrome - develop for the web
[✓] Android Studio (version 2023.1)
[✓] VS Code (version 1.98.2)
[✓] Connected device (4 available)
[✓] Network resources

• No issues found!

Thanks for the update. I think from Android side, something like workmanager would probably work, but I am not sure if there's equivalent for iOS, so I'll keep the issue open for team's tracking.

From reading FlutterEngine.mm, there are quite a few places that could have been skipped for headless mode. For example, text input plugin setup (which involves creating a few UIViews) isn't necessary for headless mode.

Hello, just chiming in that this would be really great to see fixed. We would like to run some business logic in flutter from an extension and that logic is not UI-related.

We have been trying to run the flutter engine in a Notification Service Extension. Although I believe the changes needed are the same.

Have made a PR #181645

iOS: Ensure engine is run on the main thread (flutter#191626)

iOS,macOS: Check viewType before creating a platform view (flutter#19…

Navigation Menu

Repository navigation

Error when running a headless FlutterEngine in an iOS App Extension #165904

Addition Details

Current Setup in the Extension Service

headless.dart Entrypoint:

Issues Observed

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Error when running a headless FlutterEngine in an iOS App Extension #165904

Description

Addition Details

Activity

darshankawar commented on Mar 26, 2025

AlexNik4 commented on Mar 27, 2025

Current Setup in the Extension Service

headless.dart Entrypoint:

Issues Observed

darshankawar commented on Mar 28, 2025

hellohuanlin commented on Apr 18, 2025

dyaboykyl commented on Nov 14, 2025

Gibbo97 commented on Jan 29, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions