Capacitor Android Troubleshooting: Häufige Fehler und Lösungen

Die meisten Capacitor-Android-Build-Fehler entstehen durch Toolchain-Mismatches: das falsche JDK, ein veralteter Gradle-Wrapper oder ein SDK-Level, das nicht mit den Anforderungen einer Abhängigkeit übereinstimmt. Für Capacitor 8 nutze JDK 21, Android Gradle Plugin 8.13.0, Gradle 8.14.3, compileSdk und targetSdk 36 sowie minSdk 24, und führe dann aus bunx cap sync android und lies den ersten Gradle-Fehler, nicht den letzten.

Dieser Guide listet die häufigsten Android-Fehler in Capacitor-Projekten auf, gruppiert danach, wo sie auftreten: Gradle-Setup, Dependency Resolution, Kompilierung, Installation und Runtime. Für iOS siehe den Capacitor iOS-Troubleshooting-Guide.

Schnelle Triage-Checkliste

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

Prüfe dann die erwarteten Werte für deine Capacitor-Version:

Wenn du mitten im Upgrade bist, folge So aktualisierst du deine Capacitor App auf Capacitor 8 zuerst.

Gradle- und JDK-Fehler

error: invalid source release: 21

Gradle läuft auf JDK 17 oder älter, aber @capacitor/android 8 kompiliert mit Java 21. In Android Studio: Einstellungen > Build, Execution, Deployment > Build Tools > Gradle > Gradle JDK und wähle das mitgelieferte JDK 21 (JetBrains Runtime). Auf der Kommandozeile und in der 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

Das umgekehrte Problem: Du nutzt JDK 21 mit einem Gradle-Wrapper, der zu alt ist, um Java-21-Class-Dateien zu lesen. Aktualisiere den 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 wurde aktualisiert, aber der Wrapper nicht. Jede AGP-Version hat eine Mindestversion von Gradle, und AGP 8.13 braucht Gradle 8.13+. Setze den Wrapper wie oben auf 8.14.3.

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

Deine Android-Studio-Version ist älter als das AGP im Projekt. Installiere Android Studio Otter oder neuer.

SDK location not found

Gradle kann das Android SDK nicht finden. Öffne das Projekt einmal in Android Studio (es schreibt android/local.properties), oder setze die Variable:

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

Nicht committen local.properties. Sie enthält einen maschinenspezifischen Pfad.

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

Netzwerk- oder Repository-Problem. Prüfe die Proxy-Einstellungen in ~/.gradle/gradle.properties, stelle sicher google() und mavenCentral() stehen in repositories, und versuche es erneut mit --refresh-dependencies. Firmennetzwerke benötigen oft einen Mirror.

Java heap space oder GC overhead limit exceeded

Erhöhe den Gradle-Speicher in android/gradle.properties:

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

Das Capacitor-Template kommt mit -Xmx1536m, was für Apps mit vielen Plugins zu knapp ist.

Dependency- und SDK-Level-Fehler

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

compileSdkVersion liegt unter dem, was eine AndroidX-Library braucht. Setze es auf 36 in variables.gradle. Wenn der Fehler ein Plugin-Modul nennt, hardcodiert dieses Plugin einen alten Wert. Upgrade es oder patche dessen build.gradle.

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

Deine App minSdkVersion ist niedriger als die einer Dependency. Capacitor 8 benötigt 24. Erhöhe sie in variables.gradle.

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

Zwei Artefakte der Kotlin-Standardbibliothek mit überlappenden Klassen, meist weil ein Plugin eine veraltete kotlin-stdlib-jdk8. Einigt euch auf eine Kotlin-Version. Setzt kotlin_version = '2.2.20' in eurem Root- build.gradle (Plugins lesen sie über rootProject.ext) und aktualisiert Plugins, die Kotlin 1.x pinnen. Falls nötig, erzwingt die BOM in android/app/build.gradle:

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

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

Zwei Plugins nutzen unterschiedliche Versionen von Play Services oder Firebase. Die meisten Capacitor Plugins lesen Versionen aus variables.gradle sein (zum Beispiel firebaseMessagingVersion), definiert sie daher einmal dort, damit jedes Plugin denselben Wert nutzt.

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

android/capacitor.settings.gradle und android/app/capacitor.build.gradle sind veraltet. Beide werden generiert. Führt bunx cap sync android, dann Datei > Projekt mit Gradle-Dateien synchronisieren.

Kompilierungsfehler

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

AGP 8+ erfordert namespace in jedem Android-Modul. Alte Plugins deklarieren nur package in ihrem AndroidManifest.xml. Aktualisiere das Plugin. Falls keine Version verfügbar ist, patche dessen android/build.gradle:

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

und entferne das package Attribut aus seinem 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

Ein Kotlin-Modul (deins oder eines Plugins) hat eine andere jvmTarget als seine Java- targetCompatibility. In Kotlin 2.x wird sie mit compilerOptions:

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

Die alte kotlinOptions {} block ist in Kotlin 2.2 ein Fehler, daher brauchen Plugins, die es noch nutzen, ein Update oder einen Patch.

Fehler bezüglich proguard-android.txt mit AGP 9

Wenn du bereits auf AGP 9 umgestiegen bist, schlagen Plugins, die auf getDefaultProguardFile('proguard-android.txt') verweisen, fehl. Die Lösung ist proguard-android-optimize.txt. Alle Details findest du in Capacitor Plugin-Buildfehler mit AGP 9 beheben. Für Apps mit Capacitor 8 bleibt AGP 8.13 die getestete Version.

cannot find symbol R.layout.bridge_layout_main

Capacitor 8 hat das Layout umbenannt in capacitor_bridge_layout_main. Aktualisiere den Verweis in deinem MainActivity oder benutzerdefinierten Fragment.

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

Apps, die auf Android 12+ targeten, müssen android:exported in jeder Activity, jedem Service und jedem Receiver mit Intent-Filter. Füge hinzu android:exported="true" (oder false) in dein Manifest. Wenn das Element aus einem Plugin-Manifest stammt, aktualisiere oder patche das Plugin.

Installationsfehler

INSTALL_FAILED_UPDATE_INCOMPATIBLE

Eine App mit derselben ID, aber einem anderen Signierungsschlüssel ist installiert – meist ein Release-Build aus dem Play Store im Gegensatz zu deinem Debug-Build. Installiere sie zuerst deinstallieren:

adb uninstall com.example.app

Gerät wird in Android Studio nicht angezeigt oder adb devices zeigt unauthorized

Aktiviere die Entwickleroptionen und USB-Debugging, akzeptiere den RSA-Hinweis auf dem Telefon und verwende ein Datenkabel. adb kill-server && adb start-server löst die meisten festgefahrenen Zustände.

Play Console: „Ihre App unterstützt keine 16-KB-Speicherseitengrößen“

Eine native .so Bibliothek in deiner App ist nicht 16-KB-ausgerichtet. Finde das Plugin, das sie bereitstellt, und aktualisiere es. Siehe Android 16 KB Seitengröße und Capacitor Plugins.

Release-Build signieren

Fehlende oder falsche Keystore-Einstellungen führen zu Keystore file not found oder Failed to read key. Unsere Android Keystore Generator erstellt einen Keystore und die Gradle-Signing-Config. Halte den Keystore aus Git heraus und sichere ihn. Wenn du ihn verlierst, kannst du die App nicht mehr aktualisieren, außer du nutzt Play App Signing.

Runtime-Fehler

"X" plugin is not implemented on android

1. Das Plugin befindet sich in package.json und du hast bunx cap sync android nach der Installation ausgeführt.
2. Android Studio hat Gradle nach dem Sync synchronisiert (Datei > Projekt mit Gradle-Dateien synchronisieren).
3. Das Plugin erscheint in android/capacitor.settings.gradle.
4. Die Plugin-Version entspricht deiner Capacitor-Major-Version. Ein Capacitor-7-Plugin kann zwar kompiliert werden, registriert sich aber möglicherweise anders.
5. Du führst keine alte APK aus. Deinstalliere und installiere sie neu.

Leerer weißer Bildschirm

Öffne chrome://inspect und prüfe die WebView-Konsole. Häufige Ursachen:

• net::ERR_CLEARTEXT_NOT_PERMITTED beim Live-Reload: Android blockt plain HTTP. Nur für die Entwicklung, setze server.cleartext: true in der Capacitor-Konfiguration und entferne server.url vor dem Release.
• Dev-Server nicht erreichbar: binde es an 0.0.0.0, nutze deine LAN-IP, halte Handy und PC im selben Netzwerk oder leite den Port weiter mit bunx cap run android --forwardPorts 5173:5173.
• Veraltetes Android System WebView: Capacitor Checks android.minWebViewVersion (Standard 60) und loggt einen Fehler bei älteren WebViews. Geräte, die das WebView nie aktualisieren, können auch an modernem JavaScript scheitern. Das WebView-Version-Checker-Plugin kann veraltete WebViews erkennen und Nutzer zum Update auffordern.
• Build-Target zu neu für das WebView des Geräts. Setze das Bundler-Target niedriger oder füge Polyfills hinzu.
• Falsch webDir: prüfen android/app/src/main/assets/public enthält index.html.
• Defektes live update Bundle: Mit Capgo wird ein Bundle, das nie aufruft, notifyAppReady() wird nach dem Timeout automatisch zurückgerollt. Siehe die Updater-Docs.

Inhalt hinter der Statusleiste oder Navigationsleiste

Apps mit SDK 35+ nutzen Edge-to-Edge auf Android 15, Android 16 entfernte das Opt-out für Apps mit SDK 36. Capacitor 8 hat adjustMarginsForEdgeToEdgeentfernt. Insets mit der System Bars Plugin-Config und CSS behandeln:

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);
}

Mit insetsHandling: 'css', injiziert Capacitor zudem --safe-area-inset-* CSS-Variablen, was bei älteren WebViews hilft, bei denen env() null meldet.

WebView-Reload beim Rotieren oder Skalieren

Die Activity wird neu erstellt. Prüfen Sie android:configChanges in der Hauptaktivität enthalten density (hinzugefügt in Capacitor 8) zusammen mit orientation|screenSize|smallestScreenSize|screenLayout|uiMode|navigation.

Orientierungssperre wird auf Tablets ignoriert

Ab Android 16 ignorieren große Bildschirme die Orientierungsbeschränkung für Apps, die SDK 36 als Ziel haben. Eine temporäre Manifest-Opt-out-Option existiert (android.window.PROPERTY_COMPAT_ALLOW_RESTRICTED_RESIZABILITY), aber Android 17 entfernt es. Gestalte für beide Orientierungen auf großen Bildschirmen.

Debuggen, wenn der Fehler nicht aufgeführt ist

1. Lies den ersten Fehler. Ausführen ./gradlew assembleDebug --stacktrace und scrolle nach oben zum ersten FAILURE oder What went wrong.
2. Prüfe den Dependency-Tree auf Versionskonflikte: ./gradlew :app:dependencies --configuration debugRuntimeClasspath.
3. Logcat gefiltert auf dein Package für native Crashes. Capacitor loggt Plugin-Aufrufe mit dem Capacitor Tag.
4. chrome://inspect für JavaScript-Fehler.
5. Isolieren mit einem neuen bun create @capacitor/app Projekt und nur dem verdächtigen Plugin.

Weitere Tools werden im Der ultimative Guide zum Debugging von Capacitor-Apps und behandelt, wie man Android-Build-Fehler in Capacitor behebt. Wenn eher deine CI-Maschinen das Problem sind als code, Capgo Build führt Android-Builds mit dem richtigen JDK und bereits installiertem SDK aus.