Resolving "flutter_local_notifications Requires Core Library Desugaring" Error in Flutter

Problem

When building a Flutter application that uses the flutter_local_notifications package after updating the Android Gradle Plugin (AGP), you may encounter the following build error:

FAILURE: Build failed with an exception.

* What went wrong:
Execution failed for task ':app:checkDebugAarMetadata'.
> A failure occurred while executing com.android.build.gradle.internal.tasks.CheckAarMetadataWorkAction
   > An issue was found when checking AAR metadata:

       1.  Dependency ':flutter_local_notifications' requires core library desugaring to be enabled
           for :app.

This error occurs because the flutter_local_notifications plugin uses Java 8+ features that require core library desugaring, a process that brings modern Java features to older Android versions. Without enabling this feature, your build fails due to incompatible APIs.

Why This Occurs

• flutter_local_notifications relies on Java 8+ APIs like java.time
• Older Android devices don't natively support these APIs
• Desugaring rewrites bytecode to make these features work on older runtimes

Solution

Enable core library desugaring in your Android project configuration.

1. Modify app-level Gradle file (app/build.gradle)

Open android/app/build.gradle and make these changes:

android {
    compileOptions {
        // Enable core library desugaring
        coreLibraryDesugaringEnabled true
        
        // Set Java compatibility (choose either VERSION_1_8 or VERSION_11)
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
        // Or for Java 11:
        // sourceCompatibility JavaVersion.VERSION_11
        // targetCompatibility JavaVersion.VERSION_11
    }
}

dependencies {
    // Add desugaring dependency
    coreLibraryDesugaring 'com.android.tools:desugar_jdk_libs:2.0.4'
    
    // Your other dependencies
    implementation "org.jetbrains.kotlin:kotlin-stdlib-jdk7:$kotlin_version"
}

2. Modify Kotlin Gradle file (app/build.gradle.kts)

If you're using Kotlin DSL:

android {
    compileOptions {
        isCoreLibraryDesugaringEnabled = true
        sourceCompatibility = JavaVersion.VERSION_11
        targetCompatibility = JavaVersion.VERSION_11
    }
}

dependencies {
    coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:2.0.4")
}

3. Ensure Gradle Version Compatibility

In android/build.gradle, verify you're using AGP 7.0+:

buildscript {
    dependencies {
        classpath 'com.android.tools.build:gradle:8.3.0' // 7.0 or higher required
    }
}

In gradle-wrapper.properties, use compatible Gradle distribution:

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

4. Final Steps After Changes

1. Save all modified files
2. In terminal, run:

flutter clean
flutter pub get

3. Rebuild your application

Compatibility Notes

Version Matching

Use the appropriate desugar_jdk_libs version based on your AGP version:

AGP Version	Recommended desugar_jdk_libs
7.4+	2.0.3 or higher
7.3	1.2.3
4.0-7.2	1.1.9

For multiDex support (required when minSdk < 21):

android {
    defaultConfig {
        multiDexEnabled true
    }
}

dependencies {
    implementation 'androidx.multidex:multidex:2.0.1'
}

Explanation

Core Library Desugaring allows your app to use modern Java language APIs (like those in java.time, java.util.stream, etc.) on older Android versions that don't natively support them. When enabled:

1. The Gradle plugin processes your bytecode during compilation
2. Modern Java APIs are replaced with equivalent implementations
3. The desugared code works on any device running API 14+

The flutter_local_notifications package uses Java 8+ features internally, so enabling desugaring is required for compatibility. Enabling this feature adds about 5-15KB to your APK but ensures consistent functionality across all supported Android versions.

For deeper understanding, see the Official Android Desugaring Documentation.