🩺 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

Issue	Detection	Auto-Fix
Gradle version mismatch	✅	✅
AGP version mismatch	✅	✅
Kotlin version mismatch	✅	✅
Java/JDK incompatible	✅	📋 Guide
Namespace missing (AGP 8+)	✅	✅
MinSdk too low	✅	✅
Gradle cache corruption	✅	✅

iOS

Issue	Detection	Auto-Fix
CocoaPods not installed	✅	📋 Guide
CocoaPods outdated	✅	📋 Guide
Ruby version mismatch	✅	⚠️
Xcode outdated	✅	📋 Guide
Podfile issues	✅	✅
Pod cache corruption	✅	✅

Common

Issue	Detection	Auto-Fix
Flutter SDK missing	✅	—
Pubspec issues	✅	—
Build cache stale	✅	✅

🔧 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