Troubleshooting Capacitor Android: Error Umum dan Solusinya

Kebanyakan kegagalan build Capacitor Android berasal dari ketidakcocokan toolchain: JDK yang salah, Gradle wrapper yang lama, atau level SDK yang tidak cocok 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 lalu 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 Capacitor iOS.

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

Lalu pastikan nilai yang diharapkan untuk versi Capacitor Anda:

Jika sedang proses upgrade, ikuti Cara Upgrade Aplikasi Capacitor Anda ke Capacitor 8 pertama.

Error Gradle dan JDK

error: invalid source release: 21

Gradle berjalan di JDK 17 atau versi lama, tapi @capacitor/android 8 compile dengan Java 21. Di Android Studio: Settings > Build, Execution, Deployment > Build Tools > Gradle > Gradle JDK dan pilih JDK 21 yang dibundel (JetBrains Runtime). Di command line dan di 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. Perbarui 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 diperbarui tetapi wrapper tidak. Setiap versi AGP memiliki versi Gradle minimum, dan AGP 8.13 membutuhkan Gradle 8.13+. Atur 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 daripada AGP di proyek. Instal Android Studio Otter atau yang lebih baru.

SDK location not found

Gradle tidak dapat menemukan Android SDK. Buka proyek sekali di Android Studio (ia menulis android/local.properties), atau setel variabel:

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

Jangan commit local.properties. Berisi path yang spesifik untuk mesin.

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

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

Java heap space atau GC overhead limit exceeded

Naikkan memori Gradle di android/gradle.properties:

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

Template Capacitor menyediakan -Xmx1536m, yang cukup ketat untuk aplikasi dengan banyak plugin.

Kesalahan dependensi dan level 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 menjadi 36 di variables.gradle. Jika error menyebutkan modul plugin, berarti plugin tersebut menghardcode nilai lama. Upgrade plugin tersebut, atau patch build.gradle-nya.

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

Aplikasi Anda minSdkVersion lebih rendah daripada dependensi. Capacitor 8 membutuhkan 24. Naikkan di variables.gradle.

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

Dua artifact Kotlin standard library dengan class yang tumpang tindih, biasanya karena satu plugin menarik versi lama kotlin-stdlib-jdk8. Samakan versi Kotlin. Set kotlin_version = '2.2.20' di root Anda build.gradle (plugin membacanya via rootProject.ext) dan upgrade plugin yang masih 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 di-generate. 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"
}

and remove the 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) berbeda jvmTarget dari Java-nya targetCompatibility. Di Kotlin 2.x, atur dengan compilerOptions:

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

Opsi lama kotlinOptions {} block adalah error di Kotlin 2.2, jadi plugin yang masih menggunakannya perlu diupdate atau dipatch.

Error tentang proguard-android.txt dengan AGP 9

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

cannot find symbol R.layout.bridge_layout_main

Capacitor 8 mengubah nama layout menjadi capacitor_bridge_layout_main. Perbarui referensi di MainActivity atau fragment kustom.

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 yang memiliki 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

Aplikasi dengan ID yang sama tetapi kunci penandatanganan berbeda terpasang, biasanya build release dari Play Store versus build debug Anda. Uninstall terlebih dahulu:

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 yang mendukung data. adb kill-server && adb start-server memperbaiki sebagian besar kondisi macet.

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

Native .so library di app Anda tidak selaras 16 KB. Cari plugin yang menyediakannya dan upgrade. Lihat Android 16 KB page size dan plugin Capacitor.

Signing release build

Pengaturan keystore yang hilang atau salah menyebabkan Keystore file not found atau Failed to read key. Kami Generator keystore Android membuat keystore dan konfigurasi penandatanganan Gradle. Jauhkan keystore dari git dan buat backup. Kehilangan keystore berarti Anda tidak bisa memperbarui app kecuali menggunakan Play App Signing.

Error runtime

"X" plugin is not implemented on android

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

Layar putih kosong

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

• net::ERR_CLEARTEXT_NOT_PERMITTED selama live reload: Android memblokir HTTP polos. Hanya untuk pengembangan, setel 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 Lama: pengecekan Capacitor android.minWebViewVersion (default 60) dan mencatat error pada WebView lama. Perangkat yang tidak pernah update WebView juga bisa gagal menjalankan JavaScript modern. plugin pengecek versi WebView dapat mendeteksi WebView usang dan memberi prompt ke user untuk update.
• Target build terlalu baru untuk WebView perangkat. Turunkan target bundler 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+ 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 inset 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 menginjeksi --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 pada Capacitor 8) bersama dengan orientation|screenSize|smallestScreenSize|screenLayout|uiMode|navigation.

Orientation lock diabaikan di tablet

Pada Android 16+, layar besar mengabaikan penguncian orientasi untuk aplikasi yang menargetkan SDK 36. Ada opsi opt-out manifest sementara (android.window.PROPERTY_COMPAT_ALLOW_RESTRICTED_RESIZABILITY), tetapi Android 17 menghapusnya. Rancang untuk kedua orientasi di layar besar.

Cara debug jika error tidak terdaftar

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

Alat lainnya dibahas di panduan lengkap debugging app Capacitor dan cara mengatasi error build Android di Capacitor. Jika masalahnya ada di mesin CI Anda, bukan di code, Build Capgo menjalankan build Android dengan JDK yang tepat dan SDK yang sudah terpasang.