Building a LeakCanary‑Style Memory Leak Detector for Flutter

In the past two years both innovative and flagship applications have increasingly adopted Flutter, yet high memory consumption remains a common complaint from Flutter teams.

The root causes are complex, involving Dart heap management and widget design, which together create conditions for memory leaks, especially due to the three‑tree rendering architecture and Dart closures that retain references unintentionally.

Flutter renders three trees (Element, Widget, RenderObject) whose reference relationships are tangled, making analysis difficult.

Dart closures and instance methods can be passed around, causing the owning class to be retained by the method context, e.g., listeners that are not deregistered.

Developers enjoy Flutter's convenience while unknowingly suffering from memory leaks, prompting the need for an efficient detection tool.

We evaluated several detection schemes:

Monitoring State objects for leaks – but State is not the only major memory consumer.

Monitoring Layer count – difficult to trace back to the source.

Using Expando weak references – unclear which objects to monitor.

Heap snapshot comparison – generic but requires manual identification of suspect objects and timing.

Schemes 1 and 2 are incomplete, while 3 and 4 need efficiency improvements.

What is a better solution? Android’s LeakCanary efficiently detects Activity leaks; can we build a similar tool for Flutter?

LeakCanary succeeds because it monitors objects that satisfy three conditions: large memory footprint, well‑defined lifecycle with clear reclamation point, and high leak risk due to frequent usage.

Applying these criteria to Flutter, BuildContext emerges as the ideal monitoring target because it references the three rendering trees and is heavily used throughout business code.

BuildContext holds references to Element, Widget, and RenderObject trees, each of which can retain large amounts of memory. When an Element leaks, the entire tree leaks.

Key reasons BuildContext is a good monitor:

It references a large amount of memory.

It is frequently passed as a parameter, making leak risk high.

We also monitor State objects because they often hold closures that cause leaks.

// flutter_sdk/packages/flutter/lib/src/rendering/binding.dart
mixin WidgetsBinding on BindingBase, ServicesBinding, SchedulerBinding, GestureBinding, RendererBinding, SemanticsBinding {
  @override
  void drawFrame() {
    ...
    try {
      if (renderViewElement != null)
        buildOwner.buildScope(renderViewElement);
      super.drawFrame();
      // 每一帧最后回收从 Element 树中移除的 Element
      buildOwner.finalizeTree();
    } finally {
    }
  }
}

// flutter_sdk/packages/flutter/lib/src/widgets/framework.dart
class BuildOwner {
  ...
  void finalizeTree() {
    try {
      // _inactiveElements 中记录不再使用的 Element
      lockState(() {
        _inactiveElements._unmountAll(); // this unregisters the GlobalKeys
      });
    } catch () {}
  }
  ...
}

// flutter_sdk/packages/flutter/lib/src/widgets/framework.dart
class _InactiveElements {
  ...
  void _unmountAll() {
    _locked = true;
    // 将 Element 拷贝到临时变量 elements 中
    final List<Element> elements = _elements.toList()..sort(Element._sort);
    // 清空 _elements，当前方法执行完，elements 也会被回收，则全部 Element 正常情况下都会被 GC 回收。
    _elements.clear();
    try {
      elements.reversed.forEach(_unmount);
    } finally {
      assert(_elements.isEmpty);
      _locked = false;
    }
  }
  ...
}

After finalization, any Element that remains referenced indicates a leak.

We expose a weak‑reference API in the Hummer engine:

// Add an object to be monitored
external void leakAdd(Object suspect, {String tag: ''});
// Check for leaks (triggers Full GC)
external void leakCheck({Object? callback, String tag: '', bool clear: true});
external void leakClear({String tag: ''});
external String leakCount();
external List<String> leakTags();

Leak detection is triggered at appropriate moments: BuildContext is added during _unmount, State during its unmount, and checks are performed when a page exits.

// In finalizeTree's _unmount
if (!kReleaseMode && debugMemoryLeakCheckEnabled && debugLeakAddCallback != null) {
  debugLeakAddCallback(_state);
}

// In Route exit
if (!kReleaseMode && debugMemoryLeakCheckEnabled && debugLeakCheckCallback != null) {
  debugLeakCheckCallback();
}

We built three tool variants:

DevTools resource panel integration for automatic/manual detection.

Standalone app that pops up leak details when a page leaks.

Automated testing suite that generates leak reports.

Demo screenshots show StatelessWidget and StatefulWidget leaks detected via timers and static references.

In a real‑world UC content app, the tool instantly identified previously hard‑to‑find leaks, reducing OOM crashes dramatically.

Another pure Flutter app also revealed multiple leak scenarios after integration.

Overall, the proposed solution offers:

Higher accuracy by directly monitoring BuildContext, State, and core widgets.

Greater efficiency through automated detection and concise reference chains.

Zero impact on business code, reducing developer burden.

This is the first industry‑level, logically complete, high‑value, and automated memory‑leak detection tool for Flutter.