Background Isolates and Plugin Access

By Michael Samuel Naeem · September 19, 2024 · 5 min read

I moved JSON parsing for a 12 MB API response into compute() and the app crashed with "Bad state: No BinaryMessenger registered." The parsing was off the UI thread—good—but the code also logged through a plugin-based crash reporter inside the isolate. Platform channels live on the root isolate unless you explicitly bridge them. Background isolates and plugin access is one of Flutter's sharper edges; once you understand RootIsolateToken, the pattern is straightforward.

Why isolates can't call plugins by default

Flutter's engine connects Dart to native code through BinaryMessenger. The root isolate registers this messenger at startup. Spawned isolates get a fresh Dart heap with no messenger—MethodChannel.invokeMethod has nowhere to go.

This affects any plugin: path_provider, sqflite, Firebase SDKs, shared_preferences, custom platform channels. Pure Dart packages (crypto, archive) work fine in isolates without setup.

The RootIsolateToken pattern

Flutter 3.7+ provides explicit background isolate registration:

Main isolate — capture and pass the token:

Future<R> runInBackground<R>(
  Future<R> Function() task,
) async {
  final token = RootIsolateToken.instance!;
  return Isolate.run(() async {
    BackgroundIsolateBinaryMessenger.ensureInitialized(token);
    return task();
  });
}

Inside the background task — plugins now work:

Future<void> processAndSave() async {
  await runInBackground(() async {
    final dir = await getApplicationDocumentsDirectory(); // path_provider works
    final file = File('${dir.path}/output.json');
    await file.writeAsString(largeJsonString);
  });
}

Without ensureInitialized, getApplicationDocumentsDirectory() throws.

compute() vs Isolate.run vs spawn

compute requires a top-level or static callback—you can't pass closures capturing widget state. Serialize inputs:

// Top-level function required for compute
Future<List<Item>> _parseItems(String json) async {
  BackgroundIsolateBinaryMessenger.ensureInitialized(
    // Token must be passed as part of message — see pattern below
  );
  return parseItemsFromJson(json);
}

Practical pattern — pass token with payload:

class _IsolatePayload {
  final RootIsolateToken token;
  final String json;
  _IsolatePayload(this.token, this.json);
}

List<Item> _parseInIsolate(_IsolatePayload payload) {
  BackgroundIsolateBinaryMessenger.ensureInitialized(payload.token);
  return parseItemsFromJson(payload.json);
}

// Usage
final items = await compute(
  _parseInIsolate,
  _IsolatePayload(RootIsolateToken.instance!, jsonString),
);

Long-lived worker isolates

For repeated heavy work—image thumbnails, batch encryption—spawn once:

class WorkerIsolate {
  late SendPort _sendPort;
  late Isolate _isolate;

  Future<void> start() async {
    final token = RootIsolateToken.instance!;
    final receivePort = ReceivePort();
    _isolate = await Isolate.spawn(_workerMain, [receivePort.sendPort, token]);
    _sendPort = await receivePort.first as SendPort;
  }

  static void _workerMain(List<dynamic> args) {
    final mainSendPort = args[0] as SendPort;
    final token = args[1] as RootIsolateToken;
    BackgroundIsolateBinaryMessenger.ensureInitialized(token);

    final port = ReceivePort();
    mainSendPort.send(port.sendPort);
    port.listen((message) {
      // Handle work, reply via message
    });
  }
}

Amortizes isolate startup cost (~2–5 ms) across many tasks.

What still doesn't work in background isolates

Even with token registration:

• UI operations — WidgetsBinding, BuildContext, anything rendering-related.
• Some plugins that assume main-thread-only native callbacks may still break. Test each plugin individually.
• Shared mutable state — isolates don't share memory; pass copies or use ports.

Firebase has mixed support—Firestore offline cache and some analytics calls work; others document main-isolate-only restrictions. Read plugin docs before assuming compatibility.

Debugging isolate plugin failures

Symptoms and fixes:

Enable verbose logging:

debugPrint('Isolate ${Isolate.current.debugName} calling plugin');

When not to bother with isolates

Don't spawn isolates for:

• Small JSON (< 100 KB)—parsing cost is less than spawn overhead.
• Network requests—already async, handled by native side.
• Work that must update UI immediately—results still hop back to main isolate via ports or Future completion.

Profile with DevTools CPU profiler. If frames aren't dropping, you may not need the complexity.

Structured payload classes for isolate messages

Define explicit message types instead of passing loose Maps:

@immutable
class ParseJob {
  const ParseJob({required this.token, required this.json});
  final RootIsolateToken token;
  final String json;
}

List<Item> parseJob(ParseJob job) {
  BackgroundIsolateBinaryMessenger.ensureInitialized(job.token);
  return parseItemsFromJson(job.json);
}

Version message contracts when changing isolate workers—old app versions may still receive queued jobs after OTA updates. Keep payloads immutable and small; pass file paths for megabyte data instead of copying strings across isolates.

Profile isolate message copy cost with DevTools—large strings duplicate memory during transfer. For image bytes, always prefer TransferableTypedData. Document which plugins your team verified in background isolates; maintain internal compatibility matrix updated when upgrading Flutter SDK.

Production teams should treat this guidance as living documentation: revisit assumptions after major platform upgrades, measure outcomes with real metrics rather than checklist compliance, and pair written standards with automated checks in CI. The patterns here reflect what held up in shipped apps—not theoretical perfection. Adapt thresholds, timeouts, and tooling to your stack, but keep the underlying principles: explicit configuration, testable behavior, and failure modes users can understand.

When onboarding new engineers, walk through one end-to-end example in a debug build before asking them to extend the pattern. Most failures I have seen came from skipped platform setup steps—manifest entries, API keys, code generation, or permission prompts—not from misunderstanding the Dart layer. Keep a troubleshooting section in your team wiki linking official docs and the exact commands that worked for your last upgrade.

Resources

• BackgroundIsolateBinaryMessenger API
• RootIsolateToken API
• Flutter Concurrency Documentation
• Isolate.run API
• compute function