Dépannage Capacitor Android : erreurs courantes et solutions

La plupart des échecs de build Android Capacitor viennent d'une incompatibilité de toolchain : un mauvais JDK, un wrapper Gradle obsolète ou un niveau SDK qui ne correspond pas à ce dont une dépendance a besoin. Pour Capacitor 8, utilisez JDK 21, Android Gradle Plugin 8.13.0, Gradle 8.14.3, compileSdk et targetSdk 36 et minSdk 24, puis lancez bunx cap sync android et lisez la première erreur Gradle, pas la dernière.

Ce guide répertorie les erreurs Android les plus fréquentes dans les projets Capacitor, regroupées par étape : configuration Gradle, résolution de dépendances, compilation, installation et exécution. Pour iOS, consultez la guide de dépannage iOS de Capacitor.

Checklist de triage rapide

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

Confirmez ensuite les valeurs attendues pour votre version Capacitor :

Si vous êtes en pleine mise à niveau, suivez Comment mettre à jour votre application Capacitor vers Capacitor 8 d'abord.

Erreurs Gradle et JDK

error: invalid source release: 21

Gradle fonctionne avec JDK 17 ou antérieur, mais @capacitor/android 8 se compile avec Java 21. Dans Android Studio : Paramètres > Build, Execution, Deployment > Build Tools > Gradle > Gradle JDK et sélectionnez le JDK 21 inclus (JetBrains Runtime). En ligne de commande et 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

Problème inverse : vous utilisez JDK 21 avec un wrapper Gradle trop ancien pour lire les fichiers de classe Java 21. Mettez à jour le 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 a été mis à jour, mais pas le wrapper. Chaque version d’AGP a une version minimale de Gradle, et AGP 8.13 nécessite Gradle 8.13+. Réglez le wrapper sur 8.14.3 comme ci-dessus.

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

Votre Android Studio est plus ancien que l’AGP du projet. Installez Android Studio Otter ou une version plus récente.

SDK location not found

Gradle ne trouve pas le SDK Android. Ouvrez le projet une fois dans Android Studio (il écrit android/local.properties), ou définissez la variable :

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

N’engagez pas local.properties. Il contient un chemin spécifique à la machine.

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

Problème de réseau ou de dépôt. Vérifiez les paramètres du proxy dans ~/.gradle/gradle.properties, assurez-vous que google() et mavenCentral() sont dans repositories, et réessayez avec --refresh-dependencies. Les réseaux d'entreprise ont souvent besoin d'un miroir.

Java heap space ou GC overhead limit exceeded

Augmentez la mémoire de Gradle dans android/gradle.properties:

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

Le template Capacitor est livré avec -Xmx1536m, ce qui est insuffisant pour les apps avec beaucoup de plugins.

Erreurs de dépendance et de niveau SDK

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

compileSdkVersion est inférieur à ce qu'une bibliothèque AndroidX nécessite. Réglez-le sur 36 dans variables.gradle. Si l'erreur mentionne un module de plugin, ce plugin code en dur une ancienne valeur. Mettez-l’à jour, ou corrigez son build.gradle.

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

L’application minSdkVersion est inférieur à celui d'une dépendance. Capacitor 8 nécessite 24. Augmentez-le dans variables.gradle.

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

Deux artefacts de la bibliothèque standard Kotlin avec des classes en double, généralement parce qu’un plugin tire une kotlin-stdlib-jdk8. Align on one Kotlin version. Set kotlin_version = '2.2.20' à la racine de votre projet build.gradle (les plugins le lisent via rootProject.ext) et mettez à niveau les plugins qui épinglent Kotlin 1.x. Si nécessaire, forcez le BOM dans android/app/build.gradle:

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

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

Deux plugins embarquent des versions différentes de Play Services ou Firebase. La plupart des plugins Capacitor lisent les versions depuis variables.gradle (par exemple firebaseMessagingVersion), afin de les définir une seule fois et que chaque plugin utilise la même valeur.

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

android/capacitor.settings.gradle et android/app/capacitor.build.gradle sont obsolètes. Les deux sont générés. Exécutez bunx cap sync android, puis Fichier > Synchroniser le projet avec les fichiers Gradle.

Erreurs de compilation

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

AGP 8+ nécessite namespace dans chaque module Android. Les anciens plugins ne déclarent que package dans leur AndroidManifest.xml. Mettez à jour le plugin. Si aucune release n’existe, appliquez un patch à son android/build.gradle:

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

et supprimez l’ package attribut de son 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 module Kotlin (le vôtre ou celui d’un plugin) a un jvmTarget que son Java targetCompatibility. Dans Kotlin 2.x, définissez-l’avec compilerOptions:

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

L'ancienne kotlinOptions {} block est une erreur dans Kotlin 2.2, les plugins qui l'utilisent encore nécessitent donc une mise à jour ou un patch.

Erreurs concernant proguard-android.txt avec AGP 9

Si vous êtes déjà passé à AGP 9, les plugins qui font référence à getDefaultProguardFile('proguard-android.txt') échouent. Le correctif consiste à proguard-android-optimize.txt. Tous les détails dans corriger les erreurs de build du plugin Capacitor avec AGP 9. Pour les apps Capacitor 8, AGP 8.13 reste la version testée.

cannot find symbol R.layout.bridge_layout_main

Capacitor 8 a renommé le layout en capacitor_bridge_layout_main. Mettez à jour la référence dans votre MainActivity ou fragment personnalisé.

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

Les apps ciblant Android 12+ doivent définir android:exported sur chaque activité, service et receiver avec un intent filter. Ajoutez android:exported="true" (ou false) dans votre manifest. Si l'élément provient du manifest d'un plugin, mettez le plugin à jour ou patchez-le.

Erreurs d'installation

INSTALL_FAILED_UPDATE_INCOMPATIBLE

Une application avec le même ID mais une clé de signature différente est installée, généralement un build de release du Play Store plutôt que votre build de debug. Désinstallez-la d'abord :

adb uninstall com.example.app

Appareil non listé dans Android Studio ou adb devices affiche unauthorized

Activez les options développeur et le débogage USB, acceptez le prompt RSA sur le téléphone et utilisez un câble de données. adb kill-server && adb start-server corrige la plupart des états bloqués.

Play Console : « Votre application ne prend pas en charge les pages mémoire de 16 Ko »

Un build .so dans votre application n’est pas alignée sur 16 Ko. Identifiez le plugin qui la fournit et mettez-l’à jour. Voir Taille de page Android 16 Ko et plugins Capacitor.

Signer un build de release

Paramètres de keystore manquants ou incorrects Keystore file not found ou Failed to read key. Notre générateur de keystore Android en ligne crée un keystore et la configuration de signature Gradle. Gardez le keystore hors de git et faites-en une sauvegarde. En cas de perte, vous ne pourrez pas mettre à jour l’application, sauf si vous utilisez Play App Signing.

Erreurs au runtime

"X" plugin is not implemented on android

1. Le plugin se trouve dans package.json et vous avez lancé bunx cap sync android après l’avoir installé.
2. Android Studio a synchronisé Gradle après la synchronisation (Fichier > Synchroniser le projet avec les fichiers Gradle).
3. Le plugin apparaît dans android/capacitor.settings.gradle.
4. La version du plugin correspond à la version majeure de Capacitor. Un plugin Capacitor 7 peut se compiler mais s’enregistrer différemment.
5. Vous ne lancez pas un ancien APK. Désinstallez puis réinstallez.

Écran blanc vide

Ouvrez chrome://inspect et vérifiez la console WebView. Causes courantes :

• net::ERR_CLEARTEXT_NOT_PERMITTED pendant le live reload : Android bloque le HTTP simple. Pour le développement uniquement, définissez server.cleartext: true dans la configuration Capacitor, et supprimez server.url avant la release.
• Serveur de dev inaccessible: liez-l’à 0.0.0.0, utilisez votre IP LAN, gardez le téléphone et l’ordinateur sur le même réseau, ou redirigez le port avec bunx cap run android --forwardPorts 5173:5173.
• Android System WebView obsolète: Capacitor vérifie android.minWebViewVersion (défaut : 60) et journalise une erreur sur les WebViews plus anciennes. Les appareils qui ne mettent jamais à jour la WebView peuvent également échouer sur le JavaScript moderne. Le plugin de vérification de la version WebView peut détecter les WebView obsolètes et inviter les utilisateurs à les mettre à jour.
• Cible de build trop récente pour le WebView de l’appareil. Baissez la cible de votre bundler ou ajoutez des polyfills.
• Incorrect webDir: vérifier android/app/src/main/assets/public contient index.html.
• Bundle live update corrompu: avec Capgo, un bundle qui n'appelle jamais notifyAppReady() subit un rollback automatique après le timeout. Voir le la doc de l'updater.

Contenu derrière la barre de statut ou la barre de navigation

Les apps ciblant SDK 35+ s'affichent en edge-to-edge sur Android 15, et Android 16 a supprimé l'option de désactivation pour les apps ciblant SDK 36. Capacitor 8 a supprimé adjustMarginsForEdgeToEdge. Gérez les insets avec la config du plugin System Bars et le 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);
}

Avec insetsHandling: 'css', Capacitor injecte également --safe-area-inset-* les variables CSS, qui aident sur les WebViews plus anciennes où env() indique zéro.

WebView reloads when rotating or resizing

L'activité est en cours de recréation. Vérifiez android:configChanges sur l'activité principale inclut density (ajouté dans Capacitor 8) ainsi que orientation|screenSize|smallestScreenSize|screenLayout|uiMode|navigation.

Orientation lock ignored on tablets

On Android 16+, large screens ignore orientation locks for apps targeting SDK 36. A temporary manifest opt-out exists (android.window.PROPERTY_COMPAT_ALLOW_RESTRICTED_RESIZABILITY), mais Android 17 le supprime. Concevez vos interfaces pour les deux orientations sur les grands écrans.

Comment déboguer quand l'erreur n'est pas listée

1. Lisez la première erreur. Exécutez ./gradlew assembleDebug --stacktrace et faites défiler vers le haut jusqu'à la première FAILURE ou What went wrong.
2. Vérifiez l’arborescence des dépendances pour détecter les conflits de version : ./gradlew :app:dependencies --configuration debugRuntimeClasspath.
3. Logcat filtré sur votre package pour les crashs natifs. Capacitor journalise les appels de plugins avec le Capacitor tag.
4. chrome://inspect pour les erreurs JavaScript.
5. Isoler with a fresh bun create @capacitor/app projet vierge et uniquement le plugin suspect.

D’autres outils sont abordés dans Guide ultime pour déboguer les applications Capacitor et comment résoudre les erreurs de build Android dans Capacitor. Si vos machines CI sont le problème plutôt que code, Build Capgo exécute les builds Android avec le bon JDK et SDK déjà installés.