Flutter Build Error: Unknown Kotlin JVM Target 21

Problem Statement

When building a Flutter APK using flutter build apk, you encounter the error "Unknown Kotlin JVM target: 21" in the nb_utils module. This usually occurs when:

• Your Kotlin plugin version doesn't support Java 21 features
• A dependency requires higher Java compatibility than your project supports
• Your project configuration has outdated Kotlin settings

The error appears despite setting your Java SDK to version 11. This issue can prevent APK generation and halt your Android build process.

Primary Solution: Set JVM Target to Java 8

For most Flutter projects, the safest compatible JVM target is Java 8 (1.8). This solution works whether the nb_utils module is a local module or external dependency.

Modify your android/app/build.gradle file:

android {
    namespace "com.example.my_app"  // Add this if missing
    compileSdkVersion 34

    // Add these options inside your android block
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }

    kotlinOptions {
        jvmTarget = '1.8'  // Resolves the JVM target error
    }

    // ... rest of your configuration
}

Why This Works:

• Forces all Kotlin compilation to target Java 8 bytecode
• Bypasses dependency conflicts requiring Java 21
• Maintains compatibility with older Kotlin versions

Alternative Solution: Update Your Kotlin Environment

If you need Java 17+ features, update your entire environment:

1. Update app-level build.gradle (android/app/build.gradle):

android {
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_17
        targetCompatibility JavaVersion.VERSION_17
    }
    kotlinOptions {
        jvmTarget = '17'  // Target Java 17
    }
    // ...
}

dependencies {
    implementation "org.jetbrains.kotlin:kotlin-stdlib:1.9.20"  // Modern Kotlin version
    // ...
}

2. Update project-level build.gradle (android/build.gradle):

dependencies {
    classpath "com.android.tools.build:gradle:8.3.2"
    classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:2.0.20"
    classpath "com.google.gms:google-services:4.4.1"
}

3. Update gradle-wrapper.properties (android/gradle/wrapper/gradle-wrapper.properties):

distributionUrl=https\://services.gradle.org/distributions/gradle-8.10.2-all.zip

Verification Steps:

1. Run flutter clean in terminal
2. Execute flutter pub get
3. Attempt flutter build apk again

Compatibility Notes

• Use Java 8 solution for projects with legacy dependencies
• Java 17 configuration requires Android Studio Giraffe (2022.3.1+) or later
• Ensure matching Java versions in Android Studio (File > Project Structure > SDK Location)

Handling Third-Party Dependencies

For errors in specific modules like nb_utils:

1. Locate nb_utils in your project (Ctrl + click the import in VS Code)
2. In its android/app/build.gradle, add the same JVM target settings:

   android {
       compileOptions {
           sourceCompatibility JavaVersion.VERSION_1_8
           targetCompatibility JavaVersion.VERSION_1_8
       }
       kotlinOptions {
           jvmTarget = '1.8'
       }
   }

Preventing Future Compatibility Issues

1. Maintain consistent environment versions:

// Top-level build.gradle
ext {
    kotlin_version = '2.0.20'  // Define once, reuse everywhere
}

2. Always declare a namespace:

android {
    namespace "com.yourcompany.yourapp"
}

3. Use JDK toolchains for multi-Java environments:

android {
    compileOptions {
        sourceCompatibility = 1.8
        targetCompatibility = 1.8
        coreLibraryDesugaringEnabled true  // Enables modern Java APIs
    }
}

WARNING

Never mix compileOptions and kotlinOptions across modules without specifying versions. Inconsistent Java/Kotlin targets are the primary cause of this error.

Final Advice

For beginner Flutter projects:

1. Start with Java 8 compatibility (first solution)
2. Avoid setting JVM targets beyond 17 unless required
3. Always update all build.gradle files when changing Kotlin versions

The "Unknown Kotlin JVM target: 21" error resolves when all project components agree on a compatible Java target. The solutions provided work for both new and existing Flutter projects encountering this build failure.