Flutter Debugging

Flutter Debugging Skill

Purpose

Diagnose and resolve Flutter bugs through systematic root-cause analysis — ranked hypotheses, reproduction strategies, instrumentation plans, and confidence updates.

Scope and authority

This skill is the lead authority for:

• root-cause triage for crashes, freezes, and jank
• hypothesis generation and confidence ranking
• reproduction plan design
• instrumentation and logging strategy for debugging
• async/isolate deadlock analysis
• plugin and platform channel failure diagnosis
• release-only bug investigation
• memory leak analysis
• layout overflow debugging

When to use

• App crashes in production or during development
• Jank or ANR reported (app appears frozen)
• Bug that only appears in release builds
• Memory keeps growing (unbounded memory leak)
• Async operation hangs indefinitely
• Plugin or platform channel throws unexpectedly
• Layout overflow (RenderFlex overflowed error)
• Widget test or integration test fails intermittently

Decision engine workflow

1. Collect available evidence (crash log, stacktrace, DevTools data, reproduction steps).
2. Classify bug domain (rendering / state / async / platform / memory).
3. Generate ranked hypotheses by probability and evidence fit.
4. Design minimal reproduction plan.
5. Define instrumentation additions needed to confirm/reject hypotheses.
6. Narrow hypotheses after each evidence update.
7. Return root cause + fix + regression prevention.

Bug domain classification

Hypothesis-driven debugging (mandatory)

Always generate ranked hypotheses before suggesting fixes:

Hypothesis 1 (confidence: 0.75): [description]
  Evidence for: [what supports this]
  Evidence against: [what contradicts this]
  Validation step: [how to confirm]

Hypothesis 2 (confidence: 0.60): [description]
  ...

Hypothesis 3 (confidence: 0.20): [description]
  ...

Recommended first validation: Hypothesis 1 (highest confidence × impact)

Branching decision tree

Branch A: Dart crash analysis

1. Obtain full stack trace (Crashlytics deobfuscated stack)
2. Identify top frame:
   - Null pointer → null safety violation or unchecked nullable
   - ConcurrentModificationException → List modified during iteration
   - RangeError → index out of bounds (empty list access)
   - StateError → FutureBuilder accessed after dispose
   - UnimplementedError → abstract method not implemented
3. Trace call chain back to first user code frame
4. Check for async gap (BuildContext used after await without mounted check)

Branch B: memory leak analysis

1. Open DevTools → Memory tab
2. Take heap snapshot before and after suspected operation
3. Compare object counts between snapshots
4. Look for:
   - Growing GlobalKey count (orphaned widgets)
   - Growing StreamSubscription count (not cancelled)
   - Growing AnimationController count (not disposed)
   - Growing Timer count (not cancelled)
   - Image cache exceeding bounds
4. Find owner of leaked object via reference tree
5. Fix: ensure dispose() / cancel() / close() called in widget lifecycle

Branch C: jank investigation

1. Enable Performance Overlay (WidgetsApp.showPerformanceOverlay)
2. Identify: UI thread spike vs Raster thread spike
   
   UI thread spike:
   → Check rebuild count (DevTools → Widget Rebuild Tracker)
   → Profile with Timeline in DevTools
   → Look for: heavy build(), layout passes, synchronous I/O

   Raster thread spike:
   → Look for: complex CustomPainter, excessive layers, Clip/Opacity
   → Check: platform view compositing overhead
   → Escalate to flutter-rendering for deep analysis

3. Add tracing markers:
   Timeline.startSync('heavy_operation');
   // ... operation
   Timeline.finishSync();

Branch D: release-only bugs

Most common causes:

1. Missing deobfuscation: stacktrace is garbled → upload debug symbols to Crashlytics
2. Tree shaking removed code: reflection-based code eliminated → add @pragma('vm:entry-point')
3. Assert-guarded code: logic in assert() blocks doesn't run in release → move to runtime checks
4. Missing plugin registration: some plugins require explicit registration in release
5. Stricter null safety: release mode removes some null checks that catch in debug

// ❌ Debug-only code accidentally relied upon
assert(doSomethingImportant()); // Not called in release!

// ✅ Production-safe
final result = doSomethingImportant();
assert(result); // Optional debug assertion

Branch E: async deadlock / infinite loading

1. Add logging at every async step (entry, await, return)
2. Check for:
   - Circular awaiting (A awaits B, B awaits A)
   - FutureBuilder never completing (Future.delayed gone forever)
   - StreamController not closing
   - Riverpod provider circular dependency
3. Use timeout() wrapper to surface hangs:
   await someOperation().timeout(
     const Duration(seconds: 10),
     onTimeout: () => throw TimeoutException('Operation hung'),
   );
4. Check Riverpod provider lifecycle: is build() ever completing?

Branch F: layout overflow

RenderFlex overflowed — systematic fix:

1. Identify overflowing widget from error message (Row/Column)
2. Is it a text that can wrap? → Wrap Text in Flexible/Expanded
3. Is it a fixed-size widget in flex? → Use Flexible(child: ...) or SizedBox.shrink()
4. Is it a Column inside a ListView? → Remove unconstrained Column
5. Is it a Row/Column without Flexible/Expanded? → Add Expanded to the growing child
6. Is it caused by font scaling? → Set maxLines + overflow: TextOverflow.ellipsis
7. Use LayoutBuilder to inspect available constraints

Common Flutter-specific bugs

Anti-pattern detection

• Suggesting fixes before ranking hypotheses
• Fixing symptoms without understanding root cause
• print() debugging in production (use structured logging)
• Not deobfuscating release crash stacks before analysis
• Suggesting "try/catch everything" as a fix
• Fixing crash by suppressing error instead of resolving cause

Uncertainty protocol

• High (≥ 0.80): full crash log + reproduction steps
• Medium (0.60–0.79): partial logs or inconsistent reproduction
• Low (< 0.60): "it sometimes crashes" with no evidence

Request minimum evidence: crash log OR DevTools snapshot OR minimal reproduction case.

Cross-skill handoff payload

Use the standard payload from ../../AGENTS.md. Set requesting_skill to flutter-debugging.

Output contract

Follow global section order from ../../AGENTS.md. Also include:

• Ranked hypotheses with confidence
• Reproduction strategy
• Instrumentation plan
• Evidence that would confirm/reject each hypothesis
• Root cause + fix + regression prevention

Related resources

• references/crash-analysis-guide.md
• references/devtools-memory.md
• references/async-debugging.md
• references/release-debug-guide.md
• templates/debug-checklist.md