Troubleshooting Capacitor Android: Error Umum dan Solusinya

Sebagian besar kegagalan build Android Capacitor disebabkan oleh ketidakcocokan toolchain: JDK yang salah, Gradle wrapper lama, atau level SDK yang tidak sesuai dengan kebutuhan dependency. Untuk Capacitor 8, gunakan JDK 21, Android Gradle Plugin 8.13.0, Gradle 8.14.3, compileSdk dan targetSdk 36 serta minSdk 24, lalu jalankan bunx cap sync android dan baca error Gradle yang pertama, bukan yang terakhir.

Panduan ini merangkum error Android yang paling sering muncul di proyek Capacitor, dikelompokkan berdasarkan tahapannya: setup Gradle, resolusi dependency, kompilasi, instalasi, dan runtime. Untuk iOS, lihat panduan troubleshooting iOS Capacitor.

Checklist triage cepat

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

Kemudian pastikan nilai yang diharapkan untuk versi Capacitor Anda:

Jika sedang dalam proses upgrade, ikuti Cara Upgrade Aplikasi Capacitor ke Capacitor 8 first.

Error Gradle dan JDK

error: invalid source release: 21

Gradle berjalan di JDK 17 atau versi lama, tapi @capacitor/android 8 dikompilasi dengan Java 21. Di Android Studio: Settings > Build, Execution, Deployment > Build Tools > Gradle > Gradle JDK dan pilih bundled JDK 21 (JetBrains Runtime). Di command line dan 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

Masalah sebaliknya: Anda menjalankan JDK 21 dengan Gradle wrapper yang terlalu lama untuk membaca file class Java 21. Update wrapper-nya:

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 sudah diupdate tapi wrapper belum. Setiap versi AGP punya versi Gradle minimum, dan AGP 8.13 butuh Gradle 8.13+. Set wrapper ke 8.14.3 seperti di atas.

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

Android Studio Anda lebih lama dari AGP di proyek. Install Android Studio Otter atau yang lebih baru.

SDK location not found

Gradle tidak bisa menemukan Android SDK. Buka proyek sekali di Android Studio (ini akan menulis android/local.properties), atau set variabelnya:

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

Jangan commit local.properties. Ini berisi path spesifik mesin.

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

Masalah jaringan atau repository. Cek pengaturan proxy di ~/.gradle/gradle.properties, pastikan google() dan mavenCentral() ada di repositories, lalu coba lagi dengan --refresh-dependencies. Jaringan korporat sering kali butuh mirror.

Java heap space atau GC overhead limit exceeded

Tingkatkan memori Gradle di android/gradle.properties:

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

Template Capacitor dilengkapi dengan -Xmx1536m, yang terasa sempit untuk aplikasi dengan banyak plugin.

Error pada level dependency dan SDK

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

compileSdkVersion berada di bawah kebutuhan library AndroidX. Atur ke 36 di variables.gradle. Jika error menyebutkan modul plugin, plugin tersebut menggunakan nilai lama secara hardcode. Upgrade, atau patch build.gradle-nya.

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

App Anda minSdkVersion lebih rendah dari dependency. Capacitor 8 butuh 24. Tingkatkan di variables.gradle.

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

Dua artifak Kotlin standard library memiliki class yang tumpang tindih, biasanya karena satu plugin menarik versi lama kotlin-stdlib-jdk8. Samakan versi Kotlin. Atur kotlin_version = '2.2.20' di root Anda build.gradle (plugin membacanya via rootProject.ext) dan upgrade plugin yang mengunci Kotlin 1.x. Jika perlu, paksa BOM di android/app/build.gradle:

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

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

Dua plugin membawa versi Play Services atau Firebase yang berbeda. Sebagian besar plugin Capacitor membaca versi dari variables.gradle (contohnya firebaseMessagingVersion), jadi definisikan sekali saja di sana agar setiap plugin menggunakan nilai yang sama.

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

android/capacitor.settings.gradle dan android/app/capacitor.build.gradle sudah kedaluwarsa. Keduanya dibuat secara otomatis. Jalankan bunx cap sync android, lalu File > Sync Project with Gradle Files.

Error kompilasi

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

AGP 8+ memerlukan namespace di setiap modul Android. Plugin lama hanya mendeklarasikan package di dalam AndroidManifest.xml. Upgrade plugin tersebut. Jika belum ada rilis, patch android/build.gradle:

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

dan hapus atribut package atribut dari manifestnya.

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

Modul Kotlin (milik Anda atau plugin) memiliki jvmTarget yang berbeda dari Java targetCompatibility. Di Kotlin 2.x, atur dengan compilerOptions:

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

Versi lama kotlinOptions {} block adalah error di Kotlin 2.2, jadi plugin yang masih menggunakannya butuh update atau patch.

Error mengenai proguard-android.txt dengan AGP 9

Jika Anda sudah pindah ke AGP 9, plugin yang mereferensikan getDefaultProguardFile('proguard-android.txt') gagal. Solusinya adalah proguard-android-optimize.txt. Detail lengkap di cara fix error build plugin Capacitor dengan AGP 9. Untuk aplikasi Capacitor 8, AGP 8.13 tetap menjadi versi yang teruji.

cannot find symbol R.layout.bridge_layout_main

Capacitor 8 mengubah nama layout menjadi capacitor_bridge_layout_main. Perbarui referensi di dalam MainActivity atau custom fragment Anda.

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

Aplikasi yang menargetkan Android 12+ harus mengatur android:exported pada setiap activity, service, dan receiver dengan intent filter. Tambahkan android:exported="true" (atau false) di manifest Anda. Jika elemen berasal dari manifest plugin, upgrade atau patch plugin tersebut.

Error instalasi

INSTALL_FAILED_UPDATE_INCOMPATIBLE

Ada aplikasi dengan ID yang sama tetapi kunci signing berbeda yang terinstal, biasanya build release dari Play Store vs build debug Anda. Uninstall dulu:

adb uninstall com.example.app

Perangkat tidak terdaftar di Android Studio atau adb devices menampilkan unauthorized

Aktifkan Developer options dan USB debugging, terima prompt RSA di ponsel, dan gunakan kabel data. adb kill-server && adb start-server memperbaiki sebagian besar kondisi stuck.

Play Console: “Aplikasi Anda tidak mendukung ukuran page memori 16 KB”

Sebuah native .so library di aplikasi Anda tidak selaras (aligned) dengan 16 KB. Cari plugin yang menyediakannya dan upgrade. Lihat Android 16 KB page size dan plugin Capacitor.

Signing release build

Pengaturan keystore yang salah atau hilang menyebabkan Keystore file not found atau Failed to read key. Our Generator keystore Android membuat keystore dan Gradle signing config. Jangan masukkan keystore ke git dan pastikan sudah di-backup. Jika hilang, Anda tidak bisa update aplikasi kecuali menggunakan Play App Signing.

Kesalahan runtime

"X" plugin is not implemented on android

1. Plugin sudah ada di package.json and you ran bunx cap sync android setelah menginstalnya.
2. Android Studio melakukan sync Gradle setelah sync (File > Sync Project with Gradle Files).
3. Plugin muncul di android/capacitor.settings.gradle.
4. Versi plugin sesuai dengan Capacitor major Anda. Plugin Capacitor 7 mungkin bisa compile tapi cara registrasinya berbeda.
5. Anda tidak sedang menjalankan APK lama. Uninstall dan install ulang.

Layar putih kosong

Buka chrome://inspect dan cek konsol WebView. Penyebab umum:

• net::ERR_CLEARTEXT_NOT_PERMITTED saat live reload: Android memblokir HTTP biasa. Khusus untuk development, set server.cleartext: true di konfigurasi Capacitor, dan hapus server.url sebelum rilis.
• Dev server tidak dapat dijangkau: bind ke 0.0.0.0, gunakan IP LAN Anda, pastikan ponsel dan komputer di jaringan yang sama, atau forward port dengan bunx cap run android --forwardPorts 5173:5173.
• Android System WebView Versi Lama: pengecekan Capacitor android.minWebViewVersion (default 60) dan mencatat error pada WebView versi lama. Perangkat yang tidak pernah memperbarui WebView juga mungkin gagal menjalankan JavaScript modern. plugin WebView version checker dapat mendeteksi WebView usang dan memberi prompt ke user untuk update.
• Target build terlalu baru untuk WebView perangkat. Turunkan bundler target Anda atau tambahkan polyfills.
• Salah webDir: cek android/app/src/main/assets/public berisi index.html.
• Bundle live update rusak: dengan Capgo, bundle yang tidak pernah memanggil notifyAppReady() akan di-rollback otomatis setelah timeout. Lihat dokumentasi updater.

Konten di belakang status bar atau navigation bar

App yang menargetkan SDK 35+ akan tampil edge-to-edge di Android 15, dan Android 16 menghapus opsi opt-out untuk app yang menargetkan SDK 36. Capacitor 8 menghapus adjustMarginsForEdgeToEdge. Tangani insets dengan konfigurasi plugin System Bars dan 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);
}

Dengan insetsHandling: 'css', Capacitor juga menyuntikkan --safe-area-inset-* variabel CSS, yang membantu pada WebView versi lama di mana env() melaporkan nol.

WebView reload saat rotasi atau resize

Activity sedang dibuat ulang. Cek android:configChanges pada main activity mencakup density (ditambahkan di Capacitor 8) beserta orientation|screenSize|smallestScreenSize|screenLayout|uiMode|navigation.

Kunci orientasi diabaikan pada tablet

Pada Android 16+, layar besar mengabaikan kunci orientasi untuk aplikasi yang menargetkan SDK 36. Ada opsi opt-out manifest sementara ("android.window.PROPERTY_COMPAT_ALLOW_RESTRICTED_RESIZABILITY"), namun Android 17 akan menghapusnya. Desainlah untuk kedua orientasi pada layar besar.

Cara debug jika error tidak terdaftar

1. Baca error yang pertama. Jalankan ./gradlew assembleDebug --stacktrace dan scroll ke atas ke FAILURE atau What went wrong.
2. Periksa dependency tree untuk konflik versi: ./gradlew :app:dependencies --configuration debugRuntimeClasspath.
3. Logcat filter ke package Anda untuk crash native. Capacitor mencatat pemanggilan plugin dengan Capacitor tag.
4. chrome://inspect untuk error JavaScript.
5. Isolasi dengan yang baru bun create @capacitor/app project dan hanya plugin yang dicurigai.

Tools lainnya dibahas di panduan lengkap debugging aplikasi Capacitor dan cara mengatasi error build Android di Capacitor. Jika mesin CI Anda yang jadi masalah, bukan code, Capgo Build menjalankan build Android dengan JDK yang tepat dan SDK yang sudah terinstal.