Capacitor Android: troubleshooting, errori comuni e soluzioni

La maggior parte dei fallimenti di build Android di Capacitor deriva da un mismatch della toolchain: JDK errato, Gradle wrapper obsoleto o livello SDK non compatibile con le dipendenze. Per Capacitor 8, usa JDK 21, Android Gradle Plugin 8.13.0, Gradle 8.14.3, compileSdk e targetSdk 36 e minSdk 24, poi esegui bunx cap sync android e leggi il primo errore Gradle, non l'ultimo.

Questa guida elenca gli errori Android più comuni nei progetti Capacitor, raggruppati per fase: configurazione Gradle, risoluzione dipendenze, compilazione, installazione e runtime. Per iOS, consulta la Guida alla risoluzione problemi iOS di Capacitor.

Checklist di triage rapida

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

Poi verifica i valori attesi per la tua versione di Capacitor:

Se sei in fase di upgrade, segui Come aggiornare la tua app Capacitor a Capacitor 8 prima.

Errori Gradle e JDK

error: invalid source release: 21

Gradle gira su JDK 17 o versioni precedenti, ma @capacitor/android 8 compila con Java 21. In Android Studio: Impostazioni > Build, Execution, Deployment > Build Tools > Gradle > Gradle JDK e seleziona il JDK 21 incluso (JetBrains Runtime). Da riga di comando e in 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

Il problema opposto: usi JDK 21 con un Gradle wrapper troppo vecchio per leggere i file class di Java 21. Aggiorna il 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 è stato aggiornato ma non il wrapper. Ogni versione di AGP richiede una versione minima di Gradle; AGP 8.13 richiede Gradle 8.13+. Imposta il wrapper a 8.14.3 come sopra.

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

La tua versione di Android Studio è più vecchia dell'AGP nel progetto. Installa Android Studio Otter o una versione successiva.

SDK location not found

Gradle non trova l'Android SDK. Apri il progetto in Android Studio (scriverà android/local.properties), oppure imposta la variabile:

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

Non fare il commit di local.properties. Contiene un percorso specifico della macchina.

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

Problema di rete o del repository. Controlla le impostazioni del proxy in ~/.gradle/gradle.properties, assicurati che google() e mavenCentral() siano in repositories, e riprova con --refresh-dependencies. Le reti aziendali spesso richiedono uno mirror.

Java heap space oppure GC overhead limit exceeded

Aumenta la memoria di Gradle in android/gradle.properties:

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

Il template Capacitor include -Xmx1536m, che è un valore basso per app con molti plugin.

Errori a livello di dipendenza e SDK

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

compileSdkVersion è inferiore a quanto richiesto da una libreria AndroidX. Impostalo a 36 in variables.gradle. Se l'errore cita un modulo di un plugin, quel plugin ha un valore obsoleto hardcoded. Aggiornalo, oppure modifica il suo build.gradle.

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

Il tuo minSdkVersion è inferiore a quello di una dipendenza. Capacitor 8 richiede 24. Aumentalo in variables.gradle.

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

Due artefatti della libreria standard Kotlin con classi sovrapposte, di solito perché un plugin carica una versione vecchia kotlin-stdlib-jdk8. Allineati su una sola versione di Kotlin. Imposta kotlin_version = '2.2.20' nella directory principale build.gradle (i plugin lo leggono tramite rootProject.ext) e aggiorna i plugin che fissano Kotlin 1.x. Se necessario, forza il BOM in android/app/build.gradle:

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

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

Due plugin portano versioni diverse di Play Services o Firebase. La maggior parte dei plugin Capacitor legge le versioni da variables.gradle (ad esempio firebaseMessagingVersion), quindi definiscile una volta sola lì in modo che ogni plugin usi lo stesso valore.

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

android/capacitor.settings.gradle e android/app/capacitor.build.gradle sono obsoleti. Entrambi sono generati. Esegui bunx cap sync android, poi File > Sincronizza progetto con file Gradle.

Errori di compilazione

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

AGP 8+ richiede namespace in ogni modulo Android. I plugin vecchi dichiarano solo package in AndroidManifest.xml. Aggiorna il plugin. Se non esiste una release, correggilo android/build.gradle:

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

e rimuovi l' package attributo dal suo 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 modulo Kotlin (tuo o di un plugin) ha un diverso jvmTarget rispetto al suo Java targetCompatibility. In Kotlin 2.x, impostalo con compilerOptions:

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

Il vecchio kotlinOptions {} block è un errore in Kotlin 2.2, quindi i plugin che lo usano ancora richiedono un aggiornamento o una patch.

Errori relativi a proguard-android.txt con AGP 9

Se sei già passato ad AGP 9, i plugin che fanno riferimento a getDefaultProguardFile('proguard-android.txt') falliscono. La soluzione è proguard-android-optimize.txt. Dettagli completi in risolvere gli errori di build del plugin Capacitor con AGP 9. Per le app Capacitor 8, AGP 8.13 rimane la versione testata.

cannot find symbol R.layout.bridge_layout_main

Capacitor 8 ha rinominato il layout in capacitor_bridge_layout_main. Aggiorna il riferimento nel tuo MainActivity o nel tuo fragment personalizzato.

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

Le app destinate ad Android 12+ devono impostare android:exported su ogni activity, service e receiver con intent filter. Aggiungi android:exported="true" (o false) nel tuo manifest. Se l'elemento proviene da un manifest di un plugin, aggiorna o correggi il plugin.

Errori di installazione

INSTALL_FAILED_UPDATE_INCOMPATIBLE

È installata un'app con lo stesso ID ma con una chiave di firma diversa, di solito una build di release dal Play Store rispetto alla tua build di debug. Disinstallala prima:

adb uninstall com.example.app

Dispositivo non elencato in Android Studio o adb devices mostra unauthorized

Attiva le Opzioni sviluppatore e il debug USB, accetta la richiesta RSA sul telefono e usa un cavo dati. adb kill-server && adb start-server risolve la maggior parte degli stati bloccati.

Play Console: “La tua app non supporta dimensioni di pagina di memoria da 16 KB”

Un nativo .so nella tua app non è allineata a 16 KB. Trova il plugin che la include e aggiornalo. Vedi Dimensione di pagina Android da 16 KB e plugin Capacitor.

Firma di una build di release

Impostazioni del keystore mancanti o errate causano Keystore file not found oppure Failed to read key. Il nostro Generatore di keystore per Android crea un keystore e la configurazione di firma Gradle. Tieni il keystore fuori da git e fai un backup. Se lo perdi, non potrai aggiornare l'app a meno di non usare Play App Signing.

Errori runtime

"X" plugin is not implemented on android

1. Il plugin è in package.json e hai eseguito bunx cap sync android dopo averlo installato.
2. Android Studio ha sincronizzato Gradle dopo il sync (File > Sincronizza progetto con file Gradle).
3. Il plugin appare in android/capacitor.settings.gradle.
4. La versione del plugin corrisponde alla major di Capacitor. Un plugin Capacitor 7 potrebbe compilarsi ma registrarsi in modo diverso.
5. Non stai eseguendo un APK vecchio. Disinstalla e reinstalla.

Schermata bianca

Apri chrome://inspect e controlla la console WebView. Cause comuni:

• net::ERR_CLEARTEXT_NOT_PERMITTED durante il live reload: Android blocca HTTP semplice. Solo per lo sviluppo, imposta server.cleartext: true nella configurazione Capacitor e rimuovi server.url prima del rilascio.
• Dev server non raggiungibile: bindalo a 0.0.0.0, usa il tuo IP LAN, mantieni telefono e computer sulla stessa rete o inoltra la porta con bunx cap run android --forwardPorts 5173:5173.
• Android System WebView obsoleto: Capacitor verifica android.minWebViewVersion (default 60) e registra un errore su WebView più vecchi. I dispositivi che non aggiornano mai la WebView potrebbero fallire anche con JavaScript moderno. Il Plugin per il controllo della versione di WebView può rilevare WebView obsoleti e invitare gli utenti ad aggiornarli.
• Target di build troppo recente per la WebView del dispositivo. Riduci il target del bundler o aggiungi polyfill.
• Errato webDir: controlla android/app/src/main/assets/public contiene index.html.
• Bundle live update corrotto: con Capgo, un bundle che non chiama mai notifyAppReady() viene ripristinato automaticamente dopo il timeout. Vedi la documentazione dell'updater.

Contenuto dietro la status bar o la navigation bar

Le app con target SDK 35+ sono edge-to-edge su Android 15, e Android 16 ha rimosso l'opt-out per le app con target SDK 36. Capacitor 8 ha rimosso adjustMarginsForEdgeToEdge. Gestisci gli inset con la config del plugin System Bars e il 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 inietta anche --safe-area-inset-* variabili CSS, utili sulle WebView più vecchie dove env() restituisce zero.

La WebView si ricarica ruotando o ridimensionando

L'activity viene ricreata. Controlla android:configChanges nella main activity include density (aggiunto in Capacitor 8) insieme a orientation|screenSize|smallestScreenSize|screenLayout|uiMode|navigation.

Blocco orientamento ignorato sui tablet

Su Android 16+, gli schermi grandi ignorano i blocchi di orientamento per le app che targettizzano SDK 36. Esiste un opt-out temporaneo nel manifestandroid.window.PROPERTY_COMPAT_ALLOW_RESTRICTED_RESIZABILITY), ma Android 17 lo rimuove. Progetta per entrambe le orientazioni su schermi grandi.

Come fare il debug se l'errore non è in elenco

1. Leggi il primo errore. Esegui ./gradlew assembleDebug --stacktrace e scorri verso l'alto fino al primo FAILURE oppure What went wrong.
2. Controlla l'albero delle dipendenze per conflitti di versione: ./gradlew :app:dependencies --configuration debugRuntimeClasspath.
3. Logcat filtrato sul tuo package per i crash nativi. Capacitor logga le chiamate ai plugin con il Capacitor tag.
4. chrome://inspect per gli errori JavaScript.
5. Isola con un nuovo bun create @capacitor/app progetto e solo il plugin sospetto.

Altri strumenti sono descritti nella guida definitiva al debugging di app Capacitor e come risolvere gli errori di build Android in Capacitor. Se il problema sono le macchine CI e non il code, Build Capgo esegue build Android con il JDK corretto e SDK già installato.