Capacitor Android トラブルシューティング：よくあるエラーと解決策

Capacitor Android のビルド失敗の多くは、ツールチェーンの不一致が原因です。誤った JDK、古い Gradle wrapper、または依存関係と一致しない SDK レベルなどが挙げられます。Capacitor 8 の場合は、JDK 21、Android Gradle Plugin 8.13.0、Gradle 8.14.3、compileSdk/targetSdk 36、minSdk 24 を使用し、以下のコマンドを実行してください： bunx cap sync android そして、最後のエラーではなく、最初に出力された Gradle エラーを確認してください。

このガイドでは、Capacitor プロジェクトで頻繁に発生する Android のエラーを、Gradle の設定、依存関係の解決、コンパイル、インストール、実行時の各フェーズに分けて紹介します。iOS については、こちらの Capacitor iOS トラブルシューティングガイド.

クイック診断チェックリスト

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

次に、使用している Capacitor バージョンの期待値を以下の表で確認してください：

アップグレード中の場合は、まずこちらを Capacitor アプリを Capacitor 8 へアップグレードする方法 参照してください。

Gradle と JDK のエラー

error: invalid source release: 21

Gradle は JDK 17 以下で動作しますが、 @capacitor/android 8 は Java 21 でコンパイルされます。Android Studio では： Settings > Build, Execution, Deployment > Build Tools > Gradle > Gradle JDK bundled JDK 21 (JetBrains Runtime) を選択してください。コマンドラインおよび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

逆のパターン：JDK 21 を使用しているが、Gradle wrapper が古すぎて Java 21 のクラスファイルを読み込めない。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 は更新されましたが、wrapper が更新されていません。各 AGP バージョンには最小 Gradle バージョンがあり、AGP 8.13 には Gradle 8.13 以上が必要です。上記のように wrapper を 8.14.3 に設定してください。

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

Android Studio のバージョンがプロジェクトの AGP より古いです。Android Studio Otter 以降をインストールしてください。

SDK location not found

Gradle が Android SDK を見つけられません。一度 Android Studio でプロジェクトを開いてください（これにより、 android/local.properties)、または変数を設定してください：

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

コミットしないでください local.properties。これにはマシン固有のパスが含まれています。

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

ネットワークまたはリポジトリの問題です。次の設定を確認してください： ~/.gradle/gradle.properties、必ず google() と mavenCentral() が含まれています repositories、そして次で再試行してください: --refresh-dependencies。企業ネットワークではミラーが必要になることがよくあります。

Java heap space または GC overhead limit exceeded

Gradle のメモリを増やすには: android/gradle.properties:

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

Capacitor テンプレートには -Xmx1536mが含まれていますが、プラグインが多いアプリには厳しい設定です。

依存関係と SDK レベルのエラー

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

compileSdkVersion は AndroidX ライブラリの要件を下回っています。36 に設定してください: variables.gradle。エラーにプラグインモジュール名が示されている場合、そのプラグインは古い値をハードコードしています。アップグレードするか、 その build.gradle を修正してください。.

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

アプリの minSdkVersion が依存関係の値より低くなっています。Capacitor 8 には 24 が必要です。次で引き上げてください: variables.gradle.

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

Kotlin標準ライブラリのアーティファクトが重複しています。通常、あるプラグインが古いバージョンを kotlin-stdlib-jdk8に依存していることが原因です。Kotlinのバージョンを統一してください。ルートの kotlin_version = '2.2.20' にある build.gradle で設定し（プラグインは rootProject.ext経由でこれを読み取ります）、Kotlin 1.xに固定されているプラグインをアップグレードしてください。必要に応じて、 android/app/build.gradle:

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

Duplicate class com.google.android.gms... または com.google.firebase...

でBOMを強制指定してください。Play ServicesまたはFirebaseのバージョンが異なる2つのプラグインが混在しています。ほとんどのCapacitorプラグインは、 variables.gradle からバージョンを読み取るため（例： firebaseMessagingVersion）、そこで一度定義すれば、すべてのプラグインで同じ値が使用されます。

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

android/capacitor.settings.gradle と android/app/capacitor.build.gradle が古くなっています。どちらも生成されたものです。まず bunx cap sync androidを実行してから、 File > Sync Project with Gradle Files.

コンパイルエラー

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

AGP 8以降では namespace がすべてのAndroidモジュールで必要です。古いプラグインは package を AndroidManifest.xml内でのみ宣言しています。プラグインをアップグレードしてください。リリースがない場合は、 android/build.gradle:

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

をパッチして、manifestから package 属性を削除してください。

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

Kotlinモジュール（自作またはプラグイン）の jvmTarget がJavaの targetCompatibilityと異なっています。Kotlin 2.xでは、 compilerOptions:

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

で設定してください。従来の kotlinOptions {} block は Kotlin 2.2 でエラーとなるため、これを使用しているプラグインにはアップデートまたはパッチが必要です。

に関するエラー： proguard-android.txt AGP 9 を使用した際の

すでに AGP 9 に移行している場合、以下を参照しているプラグインは getDefaultProguardFile('proguard-android.txt') 失敗します。修正方法は proguard-android-optimize.txtです。詳細は AGP 9 での Capacitor プラグインのビルドエラーを修正する。Capacitor 8 のアプリについては、テスト済みのバージョンとして AGP 8.13 を推奨します。

cannot find symbol R.layout.bridge_layout_main

Capacitor 8 では、レイアウト名が capacitor_bridge_layout_mainに変更されました。使用中の MainActivity またはカスタム fragment 内の参照を更新してください。

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

Android 12 以上をターゲットとするアプリは、以下を設定する必要があります： android:exported intent filterを持つすべてのactivity、service、receiverに追加してください。また、 android:exported="true" (または false) をmanifestに追加します。要素がプラグインのmanifestに由来する場合は、プラグインをアップグレードするかパッチを適用してください。

インストールエラー

INSTALL_FAILED_UPDATE_INCOMPATIBLE

同じIDを持つが署名キーが異なるアプリがインストールされています（通常、Play Storeのリリースビルドとデバッグビルドの競合）。先にアンインストールしてください：

adb uninstall com.example.app

Android Studioにデバイスが表示されない、または adb devices が表示されます unauthorized

開発者オプションとUSBデバッグを有効にし、端末でRSAプロンプトを許可してください。また、データ転送対応のケーブルを使用してください。 adb kill-server && adb start-server でほとんどの停止状態が解消されます。

Play Console: 「アプリが16 KBメモリページサイズをサポートしていません」

ネイティブの .so ライブラリが16 KBアライメントされていません。そのライブラリを含むプラグインを特定し、アップグレードしてください。詳細は Android 16 KB ページサイズと Capacitor プラグイン.

リリースビルドへの署名

キーストアの設定漏れや誤りによる Keystore file not found または Failed to read key. 当社の Android keystore ジェネレーター はキーストアと Gradle の署名設定を作成します。キーストアは git に含めず、必ずバックアップを取ってください。紛失すると、Play App Signing を使用していない限り、アプリのアップデートができなくなります。

ランタイムエラー

"X" plugin is not implemented on android

1. プラグインが package.json にあり、インストール後に bunx cap sync android を実行しました。
2. 同期後に Android Studio が Gradle を同期しました (File > Sync Project with Gradle Files).
3. プラグインが以下に表示されます： android/capacitor.settings.gradle.
4. プラグインのバージョンが Capacitor のメジャーバージョンと一致しています。Capacitor 7のプラグインはコンパイルできても、登録方法が異なる場合があります。
5. 古いAPKが残っている可能性があります。一度アンインストールしてから再インストールしてください。

画面が真っ白になる

開く chrome://inspect WebViewのコンソールを確認してください。主な原因は以下の通りです：

• net::ERR_CLEARTEXT_NOT_PERMITTED ライブリロード時：AndroidはプレーンなHTTPをブロックします。開発時のみ、以下を設定してください： server.cleartext: true Capacitor の設定内で設定し、リリース前には server.url 削除してください。
• 開発サーバーに接続できない：以下にバインドしてください： 0.0.0.0、LAN IPを使用するか、スマホとPCを同じネットワークに接続し、または次でポートを転送してください： bunx cap run android --forwardPorts 5173:5173.
• 古いAndroid System WebView： Capacitor チェック android.minWebViewVersion (デフォルトは60) で、古いWebViewの場合にエラーをログ出力します。WebViewが更新されないデバイスでは、最新のJavaScriptが動作しないこともあります。 WebViewバージョンチェッカープラグイン を使用すると、古いWebViewを検出し、ユーザーにアップデートを促すことができます。
• ビルドターゲットが新しすぎる デバイスのWebViewに対してターゲットが新しすぎます。bundlerのターゲットを下げるか、polyfillを追加してください。
• 誤った webDir：確認してください android/app/src/main/assets/public が含まれています index.html.
• 壊れた live update bundle: Capgo を使用すると、呼び出しが発生しない bundle は notifyAppReady() タイムアウト後に自動的にロールバックされます。詳細は updater のドキュメントを.

ステータスバーやナビゲーションバーの背後にあるコンテンツ

SDK 35 以上をターゲットとするアプリは Android 15 で edge-to-edge が描画され、Android 16 では SDK 36 をターゲットとするアプリの opt-out が廃止されました。Capacitor 8 では adjustMarginsForEdgeToEdgeが削除されました。System Bars プラグインの設定と 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);
}

With insetsHandling: 'css'、Capacitor は次も注入します： --safe-area-inset-* CSS 変数。これにより、古い WebView でも env() が 0 と報告される問題が解決します。

回転やリサイズ時に WebView がリロードされる

Activity が再生成されています。以下を確認してください： android:configChanges MainActivityに含まれる density (Capacitor 8で追加) と共に orientation|screenSize|smallestScreenSize|screenLayout|uiMode|navigation.

タブレットでの画面回転ロックの無視

Android 16以降では、SDK 36をターゲットとするアプリにおいて、大画面デバイスでは画面回転のロックが無視されます。一時的なマニフェストによる回避策は存在しますが（android.window.PROPERTY_COMPAT_ALLOW_RESTRICTED_RESIZABILITY）、Android 17では削除されます。大画面では両方の向きに対応した設計を行ってください。

エラーがリストにない場合のデバッグ方法

1. 最初のエラーを確認してください。 実行 ./gradlew assembleDebug --stacktrace して、最初の箇所までスクロールしてください FAILURE または What went wrong.
2. 依存関係ツリーを確認 バージョン競合について: ./gradlew :app:dependencies --configuration debugRuntimeClasspath.
3. Logcat ネイティブクラッシュを確認するために、パッケージ名でフィルタリングしてください。Capacitor はプラグインの呼び出しを以下の Capacitor タグでログ出力します。
4. chrome://inspect で JavaScript エラーを確認します。
5. 切り分け 新しい bun create @capacitor/app プロジェクトと、問題と思われるプラグインのみを使用して調査してください。

その他のツールについては、こちらの Capacitor アプリのデバッグ完全ガイドで紹介しています。 と Capacitor での Android ビルドエラーの解決方法. code ではなく CI マシンに問題がある場合は、 Capgo Build 適切な JDK と SDK がインストールされた状態で Android ビルドを実行します。