checkDebugAarMetadata Failed: Read the AAR Requirement First

What checkAarMetadata is actually checking

Android libraries are distributed as AARs. AAR metadata can declare compatibility requirements for consumers, including a minimum compileSdk, minimum AGP version, and minimum compile-SDK extension. Android's documentation describes these fields as build-time requirements intended to fail early with a useful message instead of producing a later ambiguous resource or tooling error.

Fix #2 — dependency requires a higher compileSdk

minCompileSdk is a floor declared by the AAR: the consuming module's effective compileSdk must be at least that value. It is not an instruction that your project must use exactly that number, and it is not the library's minSdk. Compare the requirement printed in your error with the effective compileSdk of the module consuming that dependency.

Before raising compileSdk, confirm that the required Android platform is installed and check the actual AGP release's documented compile-SDK support/recommendation and toolchain requirements. A higher minCompileSdk does not by itself prove that AGP must change; if the current AGP cannot support the selected compile SDK cleanly, then evaluate the coherent chain dependency requirement → compileSdk → AGP → Gradle → JDK. Use the official compatibility/release guidance for the exact versions instead of assuming every compileSdk increase requires a full toolchain upgrade.

Verify: rerun the exact same module/variant task. The original minCompileSdk issue should disappear, and re-read the entire remaining metadata issue block. If another requirement remains, treat it as the next compatibility boundary rather than changing unrelated SDK values.

Fix #3 — dependency requires a newer Android Gradle Plugin

AAR metadata can declare minAgpVersion: the minimum AGP version required to consume the library. If that is the concrete issue, changing compileSdk alone does not satisfy it.

Locate where your project actually declares AGP—such as the plugins DSL, version catalog, settings/plugin management, or framework-generated build configuration—and assess the AGP upgrade as a build-toolchain change. Then check the official compatibility requirements for that AGP release: the Gradle version and JDK used to run Gradle must also be supported. Do not assume that because Android Studio launches on one JDK, the Gradle build is necessarily using that same runtime.

Verify: The build now uses an AGP version that meets the named AAR requirement, and that exact minAgpVersion metadata issue is gone.

Fix #4 — the AAR requires a compile SDK extension

AAR metadata can also declare a minimum minCompileSdkExtension. This is a separate floor for an SDK extension level used when compiling against an extension SDK. Do not collapse it into the base API number: a numerically higher compileSdk alone does not prove that the required extension level is selected and available.

Read both parts of the diagnostic: the base compile SDK/API context and the required extension level. Confirm the relevant extension SDK is installed/configured and that the project's AGP supports the configuration you intend to use. Do not change minSdk or invent an extension value merely to silence the metadata check.

Verify: The consuming module satisfies the named extension requirement and the same metadata issue no longer appears.

Fix #5 — a dependency upgrade introduced the failure

If the build was green before a library update, compare the AAR requirement reported for the new version with your current build stack. You have two legitimate directions: adopt the newer supported build capability, or use a dependency release whose documented requirements match the toolchain you intentionally support.

Verify: The selected dependency/toolchain combination is intentional and reproducible, and the same AAR metadata check passes on a clean checkout/CI environment—not only one developer machine.

Fix #6 — Flutter, React Native, or multi-module build: find who owns the Android value

The outer framework does not change what the AAR metadata means, but it can change who owns the configuration. Find the Android module/variant named by the failing task and determine where its effective compileSdk, AGP and dependencies come from. In multi-module builds, changing an unrelated module may leave the failing consumer unchanged.

Before editing generated or template-managed Android files, check whether Flutter, React Native, a framework plugin, convention plugin, version catalog, settings plugin, or root build logic supplies the value. Framework upgrades can intentionally move or regenerate Android build settings. A local edit that makes one build pass can disappear on regeneration or leave the project outside the framework's supported toolchain.

If build properties are centralized, remember that modern Android builds can define common SDK settings at project/settings level while module-level values can override them. Confirm the effective value used by the failing module, then change the authoritative source for that project—not merely the first compileSdk string you find.

Verify: Rerun the same module/variant task and confirm the original dependency requirement is gone.

Only seeing the task wrapper?

Expand the failed task in Android Studio Build Output and look immediately below the AAR metadata heading for the first numbered issue. If the IDE hides it, rerun the exact failing task shown in your build from the project root with more logging.

If the task is :feature:checkReleaseAarMetadata, rerun that task instead. The goal is to expose the dependency requirement—not to generate the longest possible Gradle log.

Official references