Systematic Flutter Debugging

Overview

Random fixes waste time and create new bugs. Quick patches mask underlying issues.

Core principle: ALWAYS find root cause before attempting fixes. Symptom fixes are failure.

Announce at start: "I'm using the flutter-debugging skill to investigate this issue."

The Iron Law

NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST

If you haven't completed Phase 1, you cannot propose fixes.

When to Use

Use for ANY Flutter technical issue:

• Widget build errors
• State management bugs
• Test failures
• UI rendering issues
• Navigation problems
• API/network errors
• Build failures
• Platform-specific issues

Use this ESPECIALLY when:

• "Just one quick fix" seems obvious
• You've already tried multiple fixes
• Previous fix didn't work
• Under time pressure

Flutter Debugging Tools

1. Console Logging

// Basic logging (truncates long output)
print('Debug: $value');

// No truncation (preferred)
debugPrint('Debug: $value');

// Conditional debug logging
import 'package:flutter/foundation.dart';
if (kDebugMode) {
  debugPrint('Only in debug mode: $value');
}

// Developer log with tags
import 'dart:developer';
log('API response', name: 'NetworkService', error: e);

2. Flutter DevTools

# Open DevTools
flutter run --start-paused
# Then press 'd' or use DevTools button in IDE

DevTools Panels:

• Widget Inspector: Widget tree, properties, layout
• Performance: Timeline, frame rendering
• Memory: Heap usage, leaks
• Network: HTTP requests/responses
• Logging: All logs in one place

3. Debug Widgets

// Show widget boundaries
debugPaintSizeEnabled = true;

// Show baseline alignments
debugPaintBaselinesEnabled = true;

// Show repaint regions
debugRepaintRainbowEnabled = true;

4. Breakpoints

// Programmatic breakpoint
import 'dart:developer';
debugger();

// Or use IDE breakpoints

The Four Phases

Phase 1: Root Cause Investigation

BEFORE attempting ANY fix:

1. Read Error Messages Carefully

════════════════════════════════════════════════════════════
EXCEPTION CAUGHT BY WIDGETS LIBRARY
════════════════════════════════════════════════════════════
The following assertion was thrown building MyWidget:
'package:flutter/src/widgets/container.dart': Failed assertion: line 287
'child != null || decoration != null || constraints != null'
════════════════════════════════════════════════════════════

Don't skip past errors! They often contain the exact solution.

2. Reproduce Consistently

# Hot reload to reproduce
r  # in terminal

# Hot restart (clears state)
R  # in terminal

# Full restart
flutter run

• Can you trigger it reliably?
• What are the exact steps?
• Does Hot Reload vs Hot Restart matter?

3. Check Recent Changes

# What changed recently?
git diff

# Recent commits
git log --oneline -10

# Diff with specific commit
git diff HEAD~3

4. Add Diagnostic Logging

class MyWidget extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    debugPrint('=== MyWidget.build() ===');
    debugPrint('context.mounted: ${context.mounted}');

    final state = context.watch<MyState>();
    debugPrint('state: $state');

    return Container(...);
  }
}

Phase 2: Pattern Analysis

1. Find Working Examples

# Search for similar working code
grep -r "similar_pattern" lib/

• What works that's similar to what's broken?
• Compare widget structure, state management

2. Compare Against References

// Reference: Working widget
class WorkingWidget extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return BlocBuilder<WorkingBloc, WorkingState>(
      builder: (context, state) => ...,
    );
  }
}

// Broken: My widget
class BrokenWidget extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    // What's different?
    return BlocBuilder<MyBloc, MyState>(
      builder: (context, state) => ...,
    );
  }
}

3. Identify Differences

List every difference, however small:

• Widget type
• State provider location
• BuildContext usage
• Lifecycle methods

Phase 3: Hypothesis and Testing

1. Form Single Hypothesis

State clearly:

"I think the issue is [X] because [Y]"

Example:

"I think the build error is because the BLoC is not provided above this widget in the widget tree"

2. Test Minimally

Make the SMALLEST possible change:

// Before (broken)
Widget build(BuildContext context) {
  final bloc = context.read<MyBloc>();
  return ...;
}

// After (testing hypothesis)
Widget build(BuildContext context) {
  debugPrint('Looking for MyBloc...');
  try {
    final bloc = context.read<MyBloc>();
    debugPrint('Found: $bloc');
  } catch (e) {
    debugPrint('Error: $e');
  }
  return ...;
}

3. Verify Before Continuing

• Did it work? → Phase 4
• Didn't work? → Form NEW hypothesis
• DON'T add more fixes on top

Phase 4: Implementation

1. Create Test Case (Optional based on priority)

For Repository/DataSource issues (Priority 1):

test('should return user when API succeeds', () async {
  // Arrange
  when(mockApi.getUser(any)).thenAnswer((_) async => userModel);

  // Act
  final result = await repository.getUser('123');

  // Assert
  expect(result, equals(userEntity));
});

2. Implement Single Fix

ONE change at a time:

// Fix the root cause identified in Phase 3
class MyWidget extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return BlocProvider(
      create: (_) => getIt<MyBloc>(),
      child: BlocBuilder<MyBloc, MyState>(...),
    );
  }
}

3. Verify Fix

# Run analysis
flutter analyze

# Run tests
flutter test

# Manual verification
flutter run
# Test the specific scenario

4. If Fix Doesn't Work

• Count: How many fixes have you tried?
• If < 3: Return to Phase 1, re-analyze
• If ≥ 3: STOP and question the architecture

Common Flutter Issues & Root Causes

Red Flags - STOP and Follow Process

If you catch yourself thinking:

• "Quick fix for now"
• "Just wrap it in a try-catch"
• "Add a null check here"
• "Just add a Container around it"
• "Maybe just hot restart"
• "It's probably a state issue, let me reset"

ALL of these mean: STOP. Return to Phase 1.

REQUIRED SUB-SKILL

After fixing the bug, you MUST invoke: → flutter-craft:flutter-verification

Verify the fix with flutter analyze, flutter test, and manual testing.

Quick Reference

Real-World Impact

• Systematic approach: 15-30 minutes to fix
• Random fixes approach: 2-3 hours of thrashing
• First-time fix rate: 95% vs 40%
• New bugs introduced: Near zero vs common