🩺 Flutter Build Doctor #

Automatically diagnose and fix Flutter build issues. Stop googling error messages.

Gradle version mismatch? AGP too old? CocoaPods cache corrupted? Namespace missing? Flutter Build Doctor detects it all and fixes it in seconds.

🔥 The Problem #

Every Flutter developer has wasted hours on:

• Unsupported class file major version 65 → Java/Gradle mismatch
• Namespace not specified → AGP 8.0+ breaking change
• CocoaPods could not find compatible versions → Pod cache corruption
• Execution failed for task ':app:compileDebugKotlin' → Kotlin version conflict

Flutter Build Doctor knows exactly what's wrong and how to fix it.

🚀 Quick Start #

Install #

dart pub global activate flutter_build_doctor

Run #

# Navigate to your Flutter project
cd my_flutter_app

# Full diagnosis
flutter_build_doctor diagnose

# Auto-fix everything
flutter_build_doctor fix --auto

# Clean all caches
flutter_build_doctor clean

📸 What It Looks Like #

╔═══════════════════════════════════════════════════════════╗
║  🔍 Flutter Build Doctor - Diagnosis                      ║
╚═══════════════════════════════════════════════════════════╝

🎯 Flutter / Common
────────────────────────────────────────
✅ Flutter SDK (3.27.1 (stable))
✅ pubspec.yaml
✅ Build Cache

📱 Android
────────────────────────────────────────
❌ Gradle Version Too Low
   Flutter 3.27 requires Gradle 8.5+. Current version 7.6.3.
   💡 Update distributionUrl in gradle-wrapper.properties.
   🔧 Auto-fixable
❌ AGP Version Too Low
   Flutter 3.27 requires AGP 8.3+. Current version 7.4.2.
   💡 Update AGP version in build.gradle.
   🔧 Auto-fixable
✅ Kotlin Version (2.0.0)
✅ Java Version (17)
✅ Min SDK Version (21)

🍎 iOS
────────────────────────────────────────
✅ CocoaPods (1.15.2)
✅ Ruby Version (3.2.2)
✅ Xcode Version (16.2)
✅ Podfile

═══════════════════════════════════════════════════════════

📋 Summary
   2 errors
   0 warnings
   9 passed

🔧 2 issue(s) can be auto-fixed

📖 CLI Commands #

# Diagnosis
flutter_build_doctor diagnose              # Full diagnosis
flutter_build_doctor diagnose --android    # Android only
flutter_build_doctor diagnose --ios        # iOS only

# Fixing
flutter_build_doctor fix                   # Interactive fix mode
flutter_build_doctor fix --auto            # Auto-fix all safe issues
flutter_build_doctor fix --dry-run         # Preview fixes without applying

# Cleaning
flutter_build_doctor clean                 # Clean all caches
flutter_build_doctor clean --gradle        # Gradle cache only
flutter_build_doctor clean --pods          # CocoaPods only
flutter_build_doctor clean --flutter       # Flutter build cache only

🔍 What It Detects #

Android #

iOS #

Common #

🔧 Programmatic API #

Use it in your own tools:

import 'package:flutter_build_doctor/flutter_build_doctor.dart';

void main() async {
  final doctor = FlutterBuildDoctor(projectRoot: '.');
  
  // Full diagnosis
  final report = await doctor.diagnose();
  print('Errors: ${report.errors.length}');
  print('Warnings: ${report.warnings.length}');
  
  // Fix auto-fixable issues
  for (final issue in report.autoFixable) {
    final result = await doctor.fix(issue);
    print(result);
  }
  
  // Or fix everything at once
  final results = await doctor.fixAll();
  
  // Clean caches
  await doctor.cleanAll();
}

📊 Version Compatibility Matrix #

Built-in knowledge of which versions work together:

final compat = VersionMatrix.getCompatibility('3.27.0');
print(compat!.gradle);  // 8.5+ (recommended: 8.11.1)
print(compat.agp);      // 8.3.0+ (recommended: 8.7.3)
print(compat.kotlin);   // 1.9.0+ (recommended: 2.1.0)
print(compat.java);     // 17+ (recommended: 21)

Covers Flutter 3.10 through 3.41.

☕ Support #

If this tool saves you time, consider buying me a coffee!

🤝 Contributing #

Contributions welcome! Especially:

• New diagnostic checks
• Updated version compatibility data
• Platform-specific fixes
• Error pattern recognition

📄 License #

MIT License - see LICENSE for details.

Made with ❤️ for the Flutter community