Solución de problemas de Capacitor Android: errores comunes y soluciones

La mayoría de los fallos de build de Capacitor en Android se deben a un desajuste del toolchain: el JDK incorrecto, un Gradle wrapper antiguo o un nivel de SDK que no coincide con lo que necesita una dependencia. Para Capacitor 8, usa JDK 21, Android Gradle Plugin 8.13.0, Gradle 8.14.3, compileSdk y targetSdk 36, y minSdk 24, luego ejecuta bunx cap sync android y lee el primer error de Gradle, no el último.

Esta guía recoge los errores de Android más comunes en proyectos de Capacitor, agrupados por dónde ocurren: configuración de Gradle, resolución de dependencias, compilación, instalación y runtime. Para iOS, consulta la Guía de troubleshooting de iOS de Capacitor.

Checklist de triage rápido

bunx cap doctor              # core, CLI and android must share the same major
node -v                      # 22+ for Capacitor 8
java -version                # 21 for Capacitor 8
bun run build && bunx cap sync android
cd android && ./gradlew assembleDebug --stacktrace

Luego, confirma los valores esperados para tu versión de Capacitor:

Si estás en plena actualización, sigue Cómo actualizar tu app de Capacitor a Capacitor 8 primero.

Errores de Gradle y JDK

error: invalid source release: 21

Gradle funciona con JDK 17 o inferior, pero @capacitor/android 8 compila con Java 21. En Android Studio: Configuración > Build, Execution, Deployment > Build Tools > Gradle > Gradle JDK y elige el JDK 21 incluido (JetBrains Runtime). En la línea de comandos y en CI:

export JAVA_HOME=$(/usr/libexec/java_home -v 21)   # macOS

# GitHub Actions
- uses: actions/setup-java@v4
  with:
    distribution: temurin
    java-version: '21'

Unsupported class file major version 65

El problema inverso: ejecutas JDK 21 con un wrapper de Gradle demasiado antiguo para leer los archivos de clase de Java 21. Actualiza el wrapper:

cd android
./gradlew wrapper --distribution-type all --gradle-version 8.14.3

Minimum supported Gradle version is 8.13. Current version is 8.11.1

AGP se actualizó, pero el wrapper no. Cada versión de AGP tiene una versión mínima de Gradle, y AGP 8.13 necesita Gradle 8.13+. Configura el wrapper en 8.14.3 como se indica arriba.

The project is using an incompatible version (AGP 8.13.0) of the Android Gradle plugin

Tu Android Studio es más antiguo que el AGP del proyecto. Instala Android Studio Otter o una versión posterior.

SDK location not found

Gradle no puede encontrar el SDK de Android. Abre el proyecto una vez en Android Studio (escribe android/local.properties), o define la variable:

export ANDROID_HOME="$HOME/Library/Android/sdk"

No hagas commit de local.properties. Contiene una ruta específica de la máquina.

Could not resolve all files for configuration / Could not GET https://dl.google.com/...

Problema de red o de repositorio. Revisa la configuración del proxy en ~/.gradle/gradle.properties, asegúrate de que google() y mavenCentral() están en repositories, e inténtalo de nuevo con --refresh-dependencies. Las redes corporativas suelen requerir un mirror.

Java heap space o GC overhead limit exceeded

Aumenta la memoria de Gradle en android/gradle.properties:

org.gradle.jvmargs=-Xmx4g -Dfile.encoding=UTF-8

La plantilla de Capacitor incluye -Xmx1536m, lo cual es insuficiente para apps con muchos plugins.

Errores de dependencia y de nivel de SDK

Dependency 'androidx.core:core:1.17.0' requires libraries and applications that depend on it to compile against version 36 or later

compileSdkVersion es inferior a lo que requiere una librería de AndroidX. Cámbialo a 36 en variables.gradle. Si el error menciona un módulo de un plugin, ese plugin tiene un valor antiguo fijo. Actualízalo o parchea su build.gradle.

Manifest merger failed : uses-sdk:minSdkVersion 23 cannot be smaller than version 24 declared in library

El de tu app minSdkVersion es inferior al de una dependencia. Capacitor 8 necesita 24. Auméntalo en variables.gradle.

Duplicate class kotlin.collections.jdk8.CollectionsJDK8Kt found in modules

Dos artefactos de la biblioteca estándar de Kotlin con clases superpuestas, normalmente porque un plugin arrastra uno antiguo kotlin-stdlib-jdk8. Unifica la versión de Kotlin. Configura kotlin_version = '2.2.20' en la raíz build.gradle (los plugins lo leen vía rootProject.ext) y actualiza los plugins que fijan Kotlin 1.x. Si es necesario, fuerza el BOM en android/app/build.gradle:

dependencies {
    implementation(platform("org.jetbrains.kotlin:kotlin-bom:2.2.20"))
}

Duplicate class com.google.android.gms... o com.google.firebase...

Dos plugins traen versiones distintas de Play Services o Firebase. La mayoría de los plugins Capacitor leen las versiones de variables.gradle (por ejemplo firebaseMessagingVersion), así que defínelas una sola vez allí para que cada plugin use el mismo valor.

Project with path ':capacitor-xxx' could not be found in project ':app'

android/capacitor.settings.gradle y android/app/capacitor.build.gradle están desactualizados. Ambos se generan. Ejecuta bunx cap sync android, luego File > Sync Project with Gradle Files.

Errores de compilación

Namespace not specified. Specify a namespace in the module's build file

AGP 8+ requiere namespace en cada módulo de Android. Los plugins antiguos solo declaran package en su AndroidManifest.xml. Actualiza el plugin. Si no existe un release, parchea su android/build.gradle:

android {
    namespace = "com.example.plugin"
}

y elimina el package atributo de su manifest.

'compileDebugJavaWithJavac' task (current target is 21) and 'compileDebugKotlin' task (current target is 17) jvm target compatibility should be set to the same Java version

Un módulo Kotlin (el tuyo o de un plugin) tiene un jvmTarget distinto al de su targetCompatibility. En Kotlin 2.x, configúralo con compilerOptions:

kotlin {
    compilerOptions {
        jvmTarget = org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_21
    }
}

El antiguo kotlinOptions {} block es un error en Kotlin 2.2, por lo que los plugins que aún lo usan necesitan una actualización o un parche.

Errores con proguard-android.txt con AGP 9

Si ya migraste a AGP 9, los plugins que referencian getDefaultProguardFile('proguard-android.txt') fallan. La solución es proguard-android-optimize.txt. Detalles completos en arreglar errores de build del plugin Capacitor con AGP 9. Para apps con Capacitor 8, AGP 8.13 sigue siendo la versión probada.

cannot find symbol R.layout.bridge_layout_main

Capacitor 8 renombró el layout a capacitor_bridge_layout_main. Actualiza la referencia en tu MainActivity o fragment personalizado.

android:exported needs to be explicitly specified for element <activity#...>

Las apps para Android 12+ deben configurar android:exported en cada activity, service y receiver con un intent filter. Añade android:exported="true" (o false) en tu manifest. Si el elemento viene del manifest de un plugin, actualiza el plugin o aplícale un patch.

Errores de instalación

INSTALL_FAILED_UPDATE_INCOMPATIBLE

Hay una app con el mismo ID pero con una signing key distinta instalada, normalmente un release build de la Play Store frente a tu debug build. Desinstálala primero:

adb uninstall com.example.app

El dispositivo no aparece en Android Studio o adb devices muestra unauthorized

Activa las opciones de desarrollador y la depuración USB, acepta el prompt RSA en el teléfono y usa un cable de datos. adb kill-server && adb start-server soluciona la mayoría de los estados bloqueados.

Play Console: “Tu app no admite tamaños de página de memoria de 16 KB”

Una .so library nativa en tu app no está alineada a 16 KB. Busca el plugin que la incluye y actualízalo. Consulta Tamaño de página de 16 KB en Android y plugins Capacitor.

Firmar un release build

Configuración de keystore ausente o incorrecta causa Keystore file not found o Failed to read key. Nuestro Generador de keystore para Android crea un keystore y la configuración de firma de Gradle. Mantén el keystore fuera de git y haz una copia de seguridad. Si lo pierdes, no podrás actualizar la app a menos que uses Play App Signing.

Errores en tiempo de ejecución

"X" plugin is not implemented on android

1. El plugin está en package.json y ejecutaste bunx cap sync android después de instalarlo.
2. Android Studio sincronizó Gradle después del sync (File > Sync Project with Gradle Files).
3. El plugin aparece en android/capacitor.settings.gradle.
4. La versión del plugin coincide con tu Capacitor mayor. Un plugin Capacitor 7 puede compilar, pero registrarse de forma diferente.
5. No estás ejecutando un APK antiguo. Desinstala y reinstala.

Pantalla en blanco

Abrir chrome://inspect y revisa la consola de WebView. Causas comunes:

• net::ERR_CLEARTEXT_NOT_PERMITTED durante el live reload: Android bloquea HTTP plano. Solo para desarrollo, configura server.cleartext: true en la configuración de Capacitor, y elimina server.url antes de la publicación.
• Servidor de desarrollo inaccesible: asígnalo a 0.0.0.0, usa tu IP de LAN, mantén el móvil y el PC en la misma red, o redirige el puerto con bunx cap run android --forwardPorts 5173:5173.
• Android System WebView desactualizado: comprobaciones de Capacitor android.minWebViewVersion (por defecto 60) y registra un error en WebViews antiguos. Los dispositivos que nunca actualizan el WebView también pueden fallar con JavaScript moderno. El plugin WebView version checker puede detectar WebViews obsoletos y pedir al usuario que los actualice.
• Build target demasiado nuevo para el WebView del dispositivo. Baja el target del bundler o añade polyfills.
• Incorrecto webDir: verificar android/app/src/main/assets/public contiene index.html.
• Bundle de live update corrupto: con Capgo, un bundle que nunca llama notifyAppReady() se revierte automáticamente tras el timeout. Consulta la docs del updater.

Contenido debajo de la barra de estado o de navegación

Las apps que apuntan a SDK 35+ muestran contenido edge-to-edge en Android 15, y Android 16 eliminó la opción de desactivarlo para apps con SDK 36. Capacitor 8 eliminado adjustMarginsForEdgeToEdge. Gestiona los insets con la config del plugin System Bars y CSS:

plugins: {
  SystemBars: {
    insetsHandling: 'css',
    initialViewportFitValueHint: 'cover',
  },
},

<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />

body {
  padding-top: env(safe-area-inset-top);
  padding-bottom: env(safe-area-inset-bottom);
}

Con insetsHandling: 'css', Capacitor también inyecta --safe-area-inset-* variables CSS, lo que ayuda en WebViews antiguas donde env() reporta cero.

WebView se recarga al rotar o redimensionar

La activity se está recreando. Revisa android:configChanges en la actividad principal incluye density (añadido en Capacitor 8) junto con orientation|screenSize|smallestScreenSize|screenLayout|uiMode|navigation.

El bloqueo de orientación se ignora en tablets

En Android 16+, las pantallas grandes ignoran los bloqueos de orientación para las apps que apuntan a SDK 36. Existe una exclusión temporal en el manifiesto (android.window.PROPERTY_COMPAT_ALLOW_RESTRICTED_RESIZABILITY), pero Android 17 la elimina. Diseña para ambas orientaciones en pantallas grandes.

Cómo depurar cuando el error no aparece en la lista

1. Lee el primer error. Ejecuta ./gradlew assembleDebug --stacktrace y desplázate hacia arriba hasta el primer FAILURE o What went wrong.
2. Revisa el árbol de dependencias para conflictos de versión: ./gradlew :app:dependencies --configuration debugRuntimeClasspath.
3. Logcat filtrado por tu paquete para fallos nativos. Capacitor registra las llamadas a plugins con la Capacitor etiqueta.
4. chrome://inspect para errores de JavaScript.
5. Aislar con un nuevo bun create @capacitor/app proyecto y solo el plugin sospechoso.

Se explican más herramientas en la guía definitiva para depurar apps Capacitor y cómo resolver errores de build de Android en Capacitor. Si el problema son tus máquinas de CI y no code, Build de Capgo ejecuta builds de Android con el JDK correcto y SDK ya instalados.