πŸ”§ FlutterFix

Make any Flutter project run instantly.
Automatically fixes Flutter, Gradle, Kotlin, and Java version conflicts with a single command.

Pub Version CI codecov License: MIT PRs Welcome

πŸš€ Why FlutterFix?

Ever cloned a Flutter project and spent hours debugging build errors?

❌ The Android Gradle plugin supports only Kotlin Gradle plugin version 1.5.20 and higher.
❌ Unsupported class file major version 61
❌ java.lang.NoClassDefFoundError: Could not initialize class org.codehaus.groovy

FlutterFix solves this in seconds.

It automatically:

  • βœ… Detects incompatible Flutter/Gradle/Kotlin/Java versions
  • βœ… Updates configuration files with correct versions
  • βœ… Fixes Android SDK mismatches
  • βœ… Cleans build caches
  • βœ… Makes any project buildable instantly

πŸ“¦ Installation

dart pub global activate flutterfix

Option 2: Local Installation

dart pub global activate --source path .

Verify Installation

flutterfix --version

🎯 Quick Start

πŸš€ Most Common Use Cases

Perfect for cloned projects - preserves the exact development environment:

cd /path/to/your/flutter/project

# One command to detect, install, and configure everything
flutterfix sync --original --install-flutter

What this does:

  1. πŸ” Detects original Flutter version from .metadata file
  2. πŸ“¦ Auto-installs that Flutter version using FVM
  3. βš™οΈ Configures .fvm/fvm_config.json to use that version
  4. πŸ”§ Applies version-compatible Gradle, AGP, and Kotlin configs
  5. 🧹 Cleans caches and updates dependencies

Then run your app:

fvm flutter run

Scenario 2: Upgrade to Latest Flutter & Compatible Configs

Use the newest Flutter version with optimal build tool versions:

cd /path/to/your/flutter/project

# Install latest Flutter version
flutterfix install

# Apply latest compatible configurations
flutterfix sync

Then run:

flutter run

Scenario 3: Quick Fix Without Installing Flutter

Already have Flutter installed? Just fix the build configuration:

cd /path/to/your/flutter/project

flutterfix sync

This updates Gradle, AGP, Kotlin, and SDK versions to match your current Flutter version.

πŸ“‹ Detailed Command Reference

Sync Command

Fix version conflicts and apply compatible configurations:

# Use current Flutter version
flutterfix sync

# Use original Flutter version (from .metadata)
flutterfix sync --original

# Use original version + auto-install if not present
flutterfix sync --original --install-flutter

# Sync specific project path
flutterfix sync --path /path/to/project

Install Command

Install Flutter versions:

# Auto-detect and install project's required version
flutterfix install

# List all available Flutter versions (176 stable versions)
flutterfix install --list

# Install specific version
flutterfix install --version 3.24

# Show version compatibility info
flutterfix install --version 3.24 --info

# Install without FVM (standalone mode)
flutterfix install --version 3.24 --no-fvm

Other Commands

# Diagnose project without fixing
flutterfix doctor

# Rollback last changes (interactive)
flutterfix rollback

# Rollback latest backup automatically
flutterfix rollback --latest

# List all backups
flutterfix rollback --list

# Restore specific backup by ID
flutterfix rollback --id <backup-id>

# Upgrade FlutterFix itself
flutterfix upgrade

# Show help
flutterfix --help

πŸŽ“ Installation Modes Explained

FlutterFix supports two installation modes for Flutter:

  • Uses FVM (Flutter Version Management)
  • Auto-installs FVM if not present
  • Manages multiple Flutter versions per project
  • Creates .fvm/fvm_config.json in your project
  • Run apps with: fvm flutter run
  • Check version: fvm flutter --version

2. Standalone Mode (Fallback)

  • Direct git clone from Flutter repository
  • Installs to ~/flutter-versions/[version]
  • Auto-configures PATH on macOS/Linux/Windows
  • No FVM dependency
  • Run apps with: flutter run
  • Triggered with --no-fvm flag

πŸ’‘ Pro Tips

Check which Flutter version will be used:

# For FVM projects
fvm flutter --version

# For standalone/system Flutter
flutter --version

Switch between Flutter versions:

# List all installed versions
fvm list

# Use different version
fvm use 3.24.5

# Run with specific version
fvm flutter run

Clean everything before running:

fvm flutter clean
fvm flutter pub get
fvm flutter run

πŸ“š Complete Workflow Examples

🎯 Example 1: Clone & Run Any Flutter Project

# Clone a Flutter project
git clone https://github.com/example/flutter-app.git
cd flutter-app

# One command to set up everything
flutterfix sync --original --install-flutter

# Run the app with the correct Flutter version
fvm flutter run

What happened:

  • βœ… Detected Flutter 3.24.5 from .metadata
  • βœ… Installed Flutter 3.24.5 using FVM
  • βœ… Configured .fvm/fvm_config.json
  • βœ… Applied Gradle 8.7, AGP 8.5.0, Kotlin 2.0.10
  • βœ… Cleaned caches and updated dependencies

🎯 Example 2: Fix Build Errors on Existing Project

cd /path/to/your/project

# Just fix the configuration
flutterfix sync

# Run with your current Flutter version
flutter run

🎯 Example 3: Upgrade Project to Latest Flutter

cd /path/to/your/project

# Install latest Flutter (3.38.1)
flutterfix install --version 3.38

# Apply latest compatible configs
flutterfix sync

# Run with the new version
fvm flutter run

🎯 Example 4: Rollback If Something Goes Wrong

# Undo the last changes
flutterfix rollback --latest

# Or choose from available backups
flutterfix rollback --list
flutterfix rollback --id <backup-id>

πŸ” Understanding --original Flag

The --original flag is the recommended approach for cloned projects:

Without --original (uses current system Flutter):

flutterfix sync
  • Uses whatever Flutter version is currently active
  • Applies compatible configs for that version
  • May upgrade/downgrade build tools

With --original (uses project's intended Flutter):

flutterfix sync --original --install-flutter
  • Reads .metadata to find original Flutter version
  • Installs that exact version
  • Applies version-specific compatible configs
  • Preserves original development environment

Key difference: --original ensures you use the same Flutter version the project was built with!

✨ Features

Feature Description
🎯 Smart Version Detection Automatically detects Flutter, Gradle, Kotlin, and Java versions
πŸ“¦ Flutter Auto-Install Installs compatible Flutter version using FVM or standalone
Compatibility Matrix Supports Flutter 2.0 to 3.38 with tested compatibility mappings
πŸ›£οΈ Auto PATH Config Automatically configures shell PATH for standalone installations
πŸ“ Auto-Configuration Updates build.gradle, gradle-wrapper.properties, and SDK settings
πŸ”™ Automatic Backups Creates backups before making changes - rollback anytime
🧹 Cache Cleaning Removes stale build artifacts that cause issues
πŸ“Š Detailed Reports Shows what was fixed and what needs attention
πŸ’‘ Zero Config Works out of the box with sensible defaults
🌍 Cross-Platform Supports macOS, Linux, and Windows

πŸ› οΈ What It Fixes

1. Gradle Version Issues

  • Updates Gradle wrapper to compatible version
  • Fixes Android Gradle Plugin (AGP) version
  • Optimizes Gradle settings for performance

2. Kotlin Version Conflicts

  • Sets correct Kotlin version based on Flutter version
  • Ensures Kotlin plugin is properly configured
  • Fixes ext.kotlin_version declarations

3. Java Compatibility

  • Updates compile options (source/target compatibility)
  • Checks Java version compatibility with Gradle
  • Configures kotlinOptions.jvmTarget

4. Android SDK Configuration

  • Updates minSdkVersion to modern standards (21+)
  • Sets appropriate compileSdk and targetSdk
  • Ensures AndroidX compatibility

5. Build Cache Issues

  • Cleans Flutter build directory
  • Removes Android build artifacts
  • Clears Gradle cache

6. Flutter Version Management

  • Auto-installs compatible Flutter version based on project requirements
  • Uses FVM (Flutter Version Management) for easy version switching
  • Fallback to standalone installation if FVM is unavailable
  • Auto-configures PATH for standalone installations (macOS/Linux/Windows)
  • Lists all available Flutter versions with compatibility info
  • Install specific versions manually
  • Supports Flutter 2.0.x to 3.38.x (all stable versions)

7. Backup & Rollback System

  • Automatic backups before any file modifications
  • Restore files to previous state with one command
  • List all available backups with timestamps
  • Clear old backups to save space
  • Backup metadata includes descriptions and timestamps

πŸ“‹ Example Output

╔═══════════════════════════════════════════╗
β•‘       πŸ”§ FlutterFix v1.0.0 πŸ”§             β•‘
β•‘   Auto-fix Flutter Build Errors           β•‘
β•šβ•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•

πŸ” Detecting installed versions...
  Flutter: 3.24.0
  Dart: 3.5.0
  Java: 17
  Gradle: 7.5
  Kotlin: 1.7.10

πŸ”Ž Analyzing project structure...
  βœ“ Valid Flutter project
  Project: my_app
  SDK: >=3.0.0 <4.0.0
  βœ“ Android configuration found

πŸ”§ Fixing Gradle configuration...
  βœ“ Gradle version updated to 8.3
  βœ“ Android Gradle Plugin updated to 8.1.0
  βœ“ Gradle settings optimized

πŸ”§ Fixing Kotlin configuration...
  βœ“ Kotlin version updated to 1.9.0
  βœ“ Kotlin plugin configured

πŸ”§ Fixing Java & SDK configuration...
  βœ“ Java 17 is compatible with Gradle 8.3
  βœ“ Java compile options fixed
  βœ“ Android SDK versions updated

═══════════════════════════════════════════
πŸ“Š Summary
═══════════════════════════════════════════
βœ… Fixed (7):
   β€’ Gradle configuration
   β€’ Kotlin configuration
   β€’ Java & SDK configuration
   β€’ Build cache cleaned
   β€’ Dependencies fetched

βœ… Project fixed successfully!
You can now run: flutter run

πŸ§ͺ Compatibility Matrix

FlutterFix supports 176 Flutter stable versions from v1.0.0 to 3.38.1. Below are the major version families:

Flutter Gradle AGP Kotlin Java Min SDK Compile/Target SDK
3.38.x 8.11 8.7.3 2.1.0 17+ 24 35
3.35.x 8.10 8.7.2 2.0.21 17+ 24 35
3.32.x 8.10 8.7.1 2.0.20 17+ 24 35
3.29.x 8.9 8.7.0 2.0.10 17+ 24 35
3.27.x 8.9 8.6.0 2.0.0 17+ 24 35
3.24.x 8.7 8.5.0 2.0.10 17+ 21 34
3.22.x 8.5 8.3.0 1.9.24 17+ 21 34
3.19.x 8.3 8.1.4 1.9.0 17+ 21 34
3.16.x 8.3 8.1.4 1.9.0 17+ 21 34
3.13.x 7.6 7.4.2 1.8.22 17+ 21 33
3.10.x 7.4 7.2.0 1.7.0 11+ 21 32
3.7.x 7.3 7.1.0 1.6.10 11+ 21 31
3.3.x 7.2 7.0.0 1.6.0 11+ 21 30
3.0.x 7.0 4.2.0 1.5.31 11+ 21 30
2.10.x 6.9 4.1.0 1.5.10 11+ 21 30
2.8.x 6.7 4.1.0 1.5.0 11+ 21 29
2.5.x 6.5 4.0.1 1.4.32 11+ 16 29
2.2.x 6.3 3.6.4 1.4.0 11+ 16 29
2.0.x 6.3 3.6.4 1.4.0 11+ 16 29

All patch versions supported (e.g., 3.7.0, 3.7.1, ..., 3.7.12, 3.24.0, ..., 3.24.5, etc.)

Recent Compatibility Updates (Nov 2025)

  • βœ… Flutter 3.16.x: Updated to AGP 8.1.4, Gradle 8.3, Kotlin 1.9.0 for Android 14 support
  • βœ… Flutter 3.19.x: Upgraded from deprecated AGP 8.0.0 to 8.1.4 with compile_sdk 34
  • βœ… Flutter 3.22.x: Enhanced with AGP 8.3.0, Kotlin 1.9.24 for better Kotlin 2.0 compatibility
  • βœ… Flutter 3.24.x: Updated to Kotlin 2.0.10 for improved stability
  • βœ… Flutter 3.13.x: Upgraded to AGP 7.4.2 for better reliability

All versions tested and verified with official Flutter/Android requirements.

πŸš€ CI/CD Integration

FlutterFix can be integrated into your CI/CD pipeline to automatically fix version conflicts.

GitHub Actions

Add FlutterFix to your GitHub Actions workflow:

name: Flutter CI

on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup Flutter
        uses: subosito/flutter-action@v2
        with:
          channel: 'stable'
      
      - name: Install FlutterFix
        run: dart pub global activate flutterfix
      
      - name: Fix version conflicts
        run: flutterfix sync
      
      - name: Run tests
        run: flutter test

For more examples, see examples/ci-cd/ directory.

Benefits in CI/CD

  • βœ… Automatic version fixing - No manual intervention needed
  • βœ… Consistent builds - Same configuration across all environments
  • βœ… Catch issues early - Detect conflicts before merging
  • βœ… Zero configuration - Works out of the box
  • βœ… Fast execution - Completes in seconds

🀝 Contributing

Contributions are welcome! Here's how you can help:

  1. 🍴 Fork the repository
  2. πŸ”¨ Create a feature branch (git checkout -b feature/amazing-feature)
  3. πŸ’Ύ Commit your changes (git commit -m 'Add amazing feature')
  4. πŸ“€ Push to the branch (git push origin feature/amazing-feature)
  5. πŸŽ‰ Open a Pull Request

Development Setup

# Clone the repo
git clone https://github.com/haraprosad/flutterfix.git
cd flutterfix

# Install dependencies
dart pub get

# Run tests
dart test

# Activate locally
dart pub global activate --source path .

πŸ“„ License

This project is licensed under the MIT License - see the LICENSE file for details.

πŸ™ Acknowledgments

  • Built with ❀️ for the Flutter community
  • Inspired by countless hours debugging version conflicts
  • Thanks to all contributors and users

πŸ“ž Support

Made with πŸ”§ by developers, for developers

⭐ Star on GitHub | πŸ“¦ View on pub.flutter-io.cn

Libraries

flutterfix