fix(flutter): Serialize Android scope updates

Route paired Android scope mutations through the same worker queue so
call order is preserved across breadcrumb and context updates. Handle
worker startup failures without delaying native SDK initialization.

Co-Authored-By: GPT-5.5 <noreply@openai.com>
Co-authored-by: Cursor <cursoragent@cursor.com>

Author: 3 people

packages/flutter/lib/src/native/java/android_core_worker.dart

@@ -52,15 +52,22 @@ class AndroidCoreWorker {
         return;
       }
       _worker = worker;
+    } catch (exception, stackTrace) {
+      internalLogger.error(
+        'Failed to start Android core worker',
+        error: exception,
+        stackTrace: stackTrace,
+      );
     } finally {
       _startFuture = null;
     }
   }
 
-  FutureOr<void> close() {
+  FutureOr<void> close() async {
+    _isClosed = true;
+    await _startFuture;
     _worker?.close();
     _worker = null;
-    _isClosed = true;
   }
 
   void captureEnvelope(
@@ -183,6 +190,25 @@ class AndroidCoreWorker {
         'add breadcrumb',
       );
 
+  FutureOr<void> clearBreadcrumbs() {
+    if (_isClosed) return null;
+
+    final client = _worker;
+    if (client == null) {
+      _clearBreadcrumbs(automatedTestMode: _config.automatedTestMode);
+      return null;
+    }
+
+    return _clearBreadcrumbsFromWorker(client);
+  }
+
+  Future<void> _clearBreadcrumbsFromWorker(Worker client) =>
+      _sendScopeUpdateToWorker(
+        client,
+        const _ClearBreadcrumbsRequest(),
+        'clear breadcrumbs',
+      );
+
   FutureOr<void> setUser(SentryUser? user) {
     if (_isClosed) return null;
 
@@ -232,6 +258,28 @@ class AndroidCoreWorker {
         'set context',
       );
 
+  FutureOr<void> removeContexts(String key) {
+    if (_isClosed) return null;
+
+    final client = _worker;
+    if (client == null) {
+      _removeContexts(key, automatedTestMode: _config.automatedTestMode);
+      return null;
+    }
+
+    return _removeContextsFromWorker(client, key);
+  }
+
+  Future<void> _removeContextsFromWorker(
+    Worker client,
+    String key,
+  ) =>
+      _sendScopeUpdateToWorker(
+        client,
+        _RemoveContextsRequest(key),
+        'remove context',
+      );
+
   Future<void> _sendScopeUpdateToWorker(
     Worker client,
     Object request,
@@ -273,12 +321,17 @@ class _AndroidCoreWorkerHandler extends WorkerHandler {
           case _AddBreadcrumbRequest request:
             _addBreadcrumb(request.breadcrumb,
                 automatedTestMode: _config.automatedTestMode);
+          case _ClearBreadcrumbsRequest _:
+            _clearBreadcrumbs(automatedTestMode: _config.automatedTestMode);
           case _SetUserRequest request:
             _setUser(request.user,
                 automatedTestMode: _config.automatedTestMode);
           case _SetContextsRequest request:
             _setContexts(request.key, request.value,
                 automatedTestMode: _config.automatedTestMode);
+          case _RemoveContextsRequest request:
+            _removeContexts(request.key,
+                automatedTestMode: _config.automatedTestMode);
           default:
             _unexpectedMessage(msg);
         }
@@ -298,6 +351,9 @@ class _AndroidCoreWorkerHandler extends WorkerHandler {
             _addBreadcrumb(request.breadcrumb,
                 automatedTestMode: _config.automatedTestMode);
             return null;
+          case _ClearBreadcrumbsRequest _:
+            _clearBreadcrumbs(automatedTestMode: _config.automatedTestMode);
+            return null;
           case _SetUserRequest request:
             _setUser(request.user,
                 automatedTestMode: _config.automatedTestMode);
@@ -306,6 +362,10 @@ class _AndroidCoreWorkerHandler extends WorkerHandler {
             _setContexts(request.key, request.value,
                 automatedTestMode: _config.automatedTestMode);
             return null;
+          case _RemoveContextsRequest request:
+            _removeContexts(request.key,
+                automatedTestMode: _config.automatedTestMode);
+            return null;
           default:
             return _unexpectedPayload(payload);
         }
@@ -354,6 +414,10 @@ class _AddBreadcrumbRequest {
   const _AddBreadcrumbRequest(this.breadcrumb);
 }
 
+class _ClearBreadcrumbsRequest {
+  const _ClearBreadcrumbsRequest();
+}
+
 class _SetUserRequest {
   final Map<String, dynamic>? user;
 
@@ -367,6 +431,12 @@ class _SetContextsRequest {
   const _SetContextsRequest(this.key, this.value);
 }
 
+class _RemoveContextsRequest {
+  final String key;
+
+  const _RemoveContextsRequest(this.key);
+}
+
 void _captureEnvelope(Uint8List envelopeData, bool containsUnhandledException,
     {bool automatedTestMode = false}) {
   JObject? id;
@@ -487,6 +557,18 @@ void _addBreadcrumb(Map<String, dynamic> breadcrumb,
   }
 }
 
+void _clearBreadcrumbs({bool automatedTestMode = false}) {
+  try {
+    native.Sentry.clearBreadcrumbs();
+  } catch (exception, stackTrace) {
+    internalLogger.error('JNI: Failed to clear breadcrumbs',
+        error: exception, stackTrace: stackTrace);
+    if (automatedTestMode) {
+      rethrow;
+    }
+  }
+}
+
 void _setUser(Map<String, dynamic>? user, {bool automatedTestMode = false}) {
   JByteArray? jBytes;
   try {
@@ -527,6 +609,22 @@ void _setContexts(String key, Object? value, {bool automatedTestMode = false}) {
   }
 }
 
+void _removeContexts(String key, {bool automatedTestMode = false}) {
+  JString? jKey;
+  try {
+    jKey = key.toJString();
+    native.SentryFlutterPlugin.removeContext(jKey);
+  } catch (exception, stackTrace) {
+    internalLogger.error('JNI: Failed to remove context',
+        error: exception, stackTrace: stackTrace);
+    if (automatedTestMode) {
+      rethrow;
+    }
+  } finally {
+    jKey?.release();
+  }
+}
+
 JByteArray _jsonToJByteArray(Object? value) =>
     JByteArray.from(encodeUtf8Json(_normalizeJson(value)));
 

packages/flutter/lib/src/native/java/sentry_native_java.dart

@@ -125,9 +125,7 @@ class SentryNativeJava extends SentryNativeChannel {
       _coreWorker?.addBreadcrumb(breadcrumb);
 
   @override
-  void clearBreadcrumbs() => tryCatchSync('clearBreadcrumbs', () {
-        native.Sentry.clearBreadcrumbs();
-      });
+  FutureOr<void> clearBreadcrumbs() => _coreWorker?.clearBreadcrumbs();
 
   @override
   FutureOr<void> setUser(SentryUser? user) => _coreWorker?.setUser(user);
@@ -137,13 +135,7 @@ class SentryNativeJava extends SentryNativeChannel {
       _coreWorker?.setContexts(key, value);
 
   @override
-  void removeContexts(String key) => tryCatchSync('removeContexts', () {
-        using((arena) {
-          final jKey = key.toJString()..releasedBy(arena);
-
-          native.SentryFlutterPlugin.removeContext(jKey);
-        });
-      });
+  FutureOr<void> removeContexts(String key) => _coreWorker?.removeContexts(key);
 
   @override
   void setTag(String key, String value) => tryCatchSync('setTag', () {

packages/flutter/test/native/android_core_worker_test_real.dart

@@ -80,6 +80,69 @@ void main() {
       expect(() => worker.close(), returnsNormally);
     });
 
+    test('logs when start fails', () async {
+      final options = SentryFlutterOptions();
+      final logs = <(SentryLevel, String)>[];
+      SentryInternalLogger.configure(
+        isEnabled: true,
+        minLevel: SentryLevel.debug,
+        logOutput: ({
+          required String name,
+          required SentryLevel level,
+          required String message,
+          Object? error,
+          StackTrace? stackTrace,
+        }) {
+          logs.add((level, message.toString()));
+        },
+      );
+
+      Future<Worker> fakeSpawn(WorkerConfig config, WorkerEntry entry) async {
+        throw StateError('spawn failed');
+      }
+
+      final worker = AndroidCoreWorker(options, spawn: fakeSpawn);
+      await worker.start();
+
+      expect(
+        logs.any((e) =>
+            e.$1 == SentryLevel.error &&
+            e.$2.contains('Failed to start Android core worker')),
+        isTrue,
+      );
+    });
+
+    test('close waits for in-flight start', () async {
+      final options = SentryFlutterOptions();
+      final spawnCompleter = Completer<Worker>();
+      late ReceivePort inbox;
+      late ReceivePort replies;
+
+      Future<Worker> fakeSpawn(WorkerConfig config, WorkerEntry entry) {
+        inbox = ReceivePort();
+        addTearDown(inbox.close);
+        replies = ReceivePort();
+        addTearDown(replies.close);
+        return spawnCompleter.future;
+      }
+
+      final worker = AndroidCoreWorker(options, spawn: fakeSpawn);
+      unawaited(Future<void>.value(worker.start()));
+
+      final closeFuture = Future<void>.value(worker.close());
+      var closeCompleted = false;
+      unawaited(closeFuture.then((_) => closeCompleted = true));
+
+      await pumpEventQueue();
+      expect(closeCompleted, isFalse);
+
+      spawnCompleter.complete(Worker(inbox.sendPort, replies));
+
+      await closeFuture;
+      expect(closeCompleted, isTrue);
+      expect(await inbox.first, '_shutdown_');
+    });
+
     test('sends envelope capture request after start', () async {
       final options = SentryFlutterOptions();
       options.debug = true;
@@ -269,6 +332,18 @@ void main() {
       });
     });
 
+    test('sends breadcrumb clear request and awaits response', () async {
+      final fixture = _Fixture();
+      final worker = fixture.getSut();
+      await worker.start();
+
+      final payload = await fixture.expectPendingRequest(
+        worker.clearBreadcrumbs(),
+      );
+
+      expect(payload.runtimeType.toString(), '_ClearBreadcrumbsRequest');
+    });
+
     test('sends user update and awaits response', () async {
       final fixture = _Fixture();
       final worker = fixture.getSut();
@@ -320,6 +395,18 @@ void main() {
         'nested': {'value': true}
       });
     });
+
+    test('sends context remove request and awaits response', () async {
+      final fixture = _Fixture();
+      final worker = fixture.getSut();
+      await worker.start();
+
+      final payload = await fixture.expectPendingRequest(
+        worker.removeContexts('fixture-key'),
+      );
+
+      expect((payload as dynamic).key, 'fixture-key');
+    });
   });
 }
 

packages/flutter/test/native/sentry_native_java_test_real.dart

@@ -121,6 +121,11 @@ class _FakeCoreWorker implements AndroidCoreWorker {
     // No-op for testing
   }
 
+  @override
+  FutureOr<void> clearBreadcrumbs() {
+    // No-op for testing
+  }
+
   @override
   void setUser(SentryUser? user) {
     // No-op for testing
@@ -130,4 +135,9 @@ class _FakeCoreWorker implements AndroidCoreWorker {
   void setContexts(String key, value) {
     // No-op for testing
   }
+
+  @override
+  FutureOr<void> removeContexts(String key) {
+    // No-op for testing
+  }
 }