Android Gradle Troubleshooting Guide

This skill provides solutions for common build errors encountered in Android projects using Gradle.

1. Duplicate Files Conflict (Packaging Options)

Error Pattern:

• More than one file was found with OS independent path 'META-INF/...'
• 2 files found with path 'META-INF/versions/9/OSGI-INF/MANIFEST.MF'

Cause: Multiple dependencies include the same file (often license files, generic manifests, or module metadata) in their JARs/AARs. Gradle doesn't know which one to include in the final APK.

Solution: Configure the packaging block in your module's build.gradle.kts (usually app/build.gradle.kts) to exclude, pick first, or merge the conflicting files.

android {
    packaging {
        resources {
            // Option 1: Exclude the file (Recommended for metadata/licenses)
            excludes += "/META-INF/{AL2.0,LGPL2.1}"
            excludes += "META-INF/versions/9/OSGI-INF/MANIFEST.MF"
            excludes += "META-INF/*.kotlin_module"
            
            // Option 2: Pick the first occurrence (If content is identical or one is sufficient)
            pickFirsts += "META-INF/DEPENDENCIES"
            pickFirsts += "META-INF/LICENSE"
            
            // Option 3: Merge files (For service loaders or configuration files)
            merges += "META-INF/services/javax.annotation.processing.Processor"
        }
    }
}

2. Manifest Merge Conflicts

Error Pattern:

• Manifest merger failed : Attribute application@appComponentFactory value=(...)
• Attribute application@allowBackup value=(true) from AndroidManifest.xml:10:9 is also present at ... value=(false)

Cause: Your app's AndroidManifest.xml defines an attribute value that conflicts with a value defined in a library dependency's manifest.

Solution: Use the tools:replace attribute in the element where the conflict occurs to explicitly tell the merger which value to keep.

<manifest xmlns:tools="http://schemas.android.com/tools">
    <application
        android:allowBackup="true"
        android:label="@string/app_name"
        tools:replace="android:allowBackup,android:label">
        <!-- ... -->
    </application>
</manifest>

3. Dependency Version Conflict

Error Pattern:

• Conflict with dependency 'com.google.guava:guava' in project ':app'. Resolved versions for app (20.0) and test app (28.1-android) differ.
• Duplicate class com.google.common.util.concurrent.ListenableFuture found in modules ...

Cause: Different dependencies rely on different versions of the same transitive dependency, or different libraries contain the same class.

Solution 1: Force a Resolution Strategy Force a specific version for the entire configuration.

// build.gradle.kts (Module level)
configurations.all {
    resolutionStrategy {
        force("com.google.guava:guava:31.1-android")
    }
}

Solution 2: Exclude Transitive Dependency Exclude the unwanted module from a specific dependency.

dependencies {
    implementation("com.example:library:1.0") {
        exclude(group = "com.google.guava", module = "guava")
    }
}

Solution 3: BOM (Bill of Materials) Use a BOM to align versions (common for Firebase/Jetpack Compose).

dependencies {
    implementation(platform("androidx.compose:compose-bom:2024.02.00"))
    implementation("androidx.compose.ui:ui") // No version needed
}

4. Kotlin/Java Version Incompatibility

Error Pattern:

• Class file has wrong version 61.0, should be 55.0
• Cannot inline bytecode built with JVM target 17 into bytecode that is being built with JVM target 1.8

Cause: The library was compiled with a newer Java/Kotlin version than what your project is configured to use.

Solution: Update compileOptions and kotlinOptions to match the required version (e.g., Java 17).

android {
    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_17
        targetCompatibility = JavaVersion.VERSION_17
    }
}

kotlin {
    jvmToolchain(17)
}

5. R8 "Sealed classes are not supported as program classes"

Error Pattern:

• Sealed classes are not supported as program classes during minification/obfuscation.

Cause: When using newer Kotlin versions (like 2.0+) with sealed classes and running on Java 17, older versions of the R8 compiler (bundled with older AGP) may crash when processing the bytecode.

Solution: Force an upgrade to the R8 compiler version in the root build.gradle.kts buildscript block.

buildscript {
    dependencies {
        // Upgrade R8 to fix Sealed class issues with Java 17 / Kotlin 2.x
        classpath("com.android.tools:r8:8.9.35")
    }
}