Skip to content
Boring Doc
BreakingHigh impactOfficial migration guidesince 3.10.0landed 3.9.0-9.0.pre

"Zone mismatch" message

Framework · Official source

Starting with Flutter 3.10, the framework detects mismatches when using Zones and reports them to the console in debug builds.

Who is affected
Applications and packages relying on the previous behaviour or signature. Code that uses Timer, BindingBase.debugZoneErrorsAreFatal, Zone.
Practical impact
Behaviour or API differences that can break builds or change runtime behaviour.
What action should I take?
Follow the official migration guide below, update affected call sites, run `dart fix --apply` where a fix is available, then run your tests.
Official migration guide (excerpt, © The Flutter Authors, CC BY 3.0)

The best way to silence this message is to remove use of Zones from within the application. Zones can be very hard to debug, because they are essentially global variables, and break encapsulation. Best practice is to avoid global variables and zones.

If removing zones is not an option (for example because the application depends on a third-party library that relies on zones for its configuration), then the various calls into the Flutter framework should be moved to all be in the same zone. Typically, this means moving the call to WidgetsFlutterBinding.ensureInitialized() to the same closure as the call to runApp().

This can be awkward when the zone in which runApp is run is being initialized with zoneValues obtained from a plugin (which requires WidgetsFlutterBinding.ensureInitialized() to have been called).

One option in this kind of scenario is to place a mutable object in the zoneValues, and update that object with the value once the value is available.

import 'dart:async';
import 'package:material_ui/material_ui.dart';

class Mutable<T> {
  Mutable(this.value);
  T value;
}

void main() {
  var myValue = Mutable<double>(0.0);
  Zone.current.fork(
    zoneValues: {
      'myKey': myValue,
    }
  ).run(() {
    WidgetsFlutterBinding.ensureInitialized();
    var newValue = ...; // obtain value from plugin
    myValue.value = newValue; // update value in Zone
    runApp(...);
  });
}

In code that needs to use myKey, it can be obtained indirectly using Zone.current['myKey'].value.

When such a solution does not work because a third-party dependency requires the use of a specific type for a specific zoneValues key, all calls into the dependency can be wrapped in Zone calls that provide suitable values.

It is strongly recommended that packages that use zones in this way migrate to more maintainable solutions.

Migration assistantAI-generated · grounded in cited sources
AI explanations are not configured
Set AI_PROVIDER (for example to openai-compatible with a local Ollama or LM Studio endpoint) to enable grounded explanations. Everything else on this page works without an AI provider.
Official migration guide·Verified classification (95%)

Listed in the official breaking-changes index (docs.flutter.dev/release/breaking-changes).

An official announcement or migration guide documents an intended behaviour or API change. A verified source change (git diff) shows code changed but does not by itself prove a public API is breaking. AI interpretations are labelled and never used to classify a change.

Source commit
b3045439b7c0
Source last updated
Oct 21, 2026
Last synchronized
Oct 21, 2026
Publication status
published
Publication history
  • Oct 21, 2026, 8:31 PM: new → published (ingestion) — Backed by an official breaking-change/migration guide.
AI explanationAI-generated · grounded in cited sources
AI explanations are not configured
Set AI_PROVIDER (for example to openai-compatible with a local Ollama or LM Studio endpoint) to enable grounded explanations. Everything else on this page works without an AI provider.
Was this useful?