Solución al Error "Provided Metadata instance has version 2.1.0" al Compilar tu APK Flutter

¿Te has encontrado con el frustrante error "Provided Metadata instance has version 2.1.0, while maximum supported version is 2.0.0" al intentar compilar tu APK Flutter? Este problema, relacionado con la incompatibilidad entre las versiones de Kotlin Metadata y el Android Gradle Plugin, es más común de lo que parece. En este tutorial, te guiaremos paso a paso para resolver este error y lograr que tu compilación de APK sea exitosa.

🔍 Contexto del Error

Al generar el APK de una app Flutter con R8 activo, es posible que te encuentres con el siguiente mensaje de error:

ERROR: R8: java.lang.IllegalArgumentException:
Provided Metadata instance has version 2.1.0,
while maximum supported version is 2.0.0.
To support newer versions, update the kotlinx-metadata-jvm library.

Este error ocurre porque la versión del Android Gradle Plugin (AGP) o del wrapper de Gradle no es compatible con los metadatos generados por Kotlin 2.1.0. Para entenderlo mejor, veamos la causa raíz.

🚨 Causa Raíz del Problema

La causa principal de este error es la siguiente:

Kotlin 2.1.0 genera metadatos de versión 2.1.0.
R8 en AGP 8.3.x (y Gradle < 8.7) solo soporta metadatos hasta 2.0.0.
Por lo tanto, al hacer minify/remap con R8, falla la lectura de los ficheros .kotlin_module.

🛠 Solución Paso a Paso

Sigue estos pasos para resolver el error:

1. Actualiza el Android Gradle Plugin a 8.6.0

En android/settings.gradle, busca el bloque plugins y cambia:

- id "com.android.application" version "8.3.2" apply false
+ id "com.android.application" version "8.6.0" apply false

2. Sube el Wrapper de Gradle a la Versión Mínima 8.7

En android/gradle/wrapper/gradle-wrapper.properties, modifica:

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

3. Limpia y Reconstruye el Proyecto

Desde la raíz del proyecto, ejecuta los siguientes comandos:

flutter clean
flutter build apk --release

Con AGP 8.6.0 y Gradle 8.7, R8 podrá procesar metadatos v2.1.0 sin errores.

✔️ Conclusión

Asegúrate de alinear lo siguiente para evitar este error:

Plugin Android con versión compatible (≥ 8.5.x, ideal 8.6.0).
Gradle wrapper a 8.7 o superior.

Al hacer estos cambios, R8 dejará de lanzar la excepción sobre el metadata de Kotlin, y tu APK Flutter se compilará satisfactoriamente en modo release. ¡Ahora puedes continuar con el despliegue de tu aplicación sin problemas!

Preguntas Frecuentes (FAQ)

¿Por qué ocurre este error?
El error ocurre debido a una incompatibilidad entre la versión de Kotlin Metadata y las versiones antiguas del Android Gradle Plugin y Gradle wrapper.
¿Qué versiones de AGP y Gradle debo usar?
Se recomienda usar AGP 8.6.0 y Gradle 8.7 o superior.
¿Es necesario limpiar el proyecto después de actualizar?
Sí, es importante ejecutar flutter clean para eliminar archivos temporales y asegurar una compilación limpia.
¿Dónde encuentro los archivos settings.gradle y gradle-wrapper.properties?
Estos archivos se encuentran en la carpeta android de tu proyecto Flutter.
¿Qué significa "minify/remap" con R8?
Minify y remap son procesos de optimización y ofuscación del código que R8 realiza para reducir el tamaño del APK y proteger el código fuente.