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

ほとんどの Capacitor Android ビルド失敗はツールチェーンの不一致が原因です。誤った JDK、古い Gradle ラッパー、依存関係が要求するレベルと合わない 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では： 設定 > Build, Execution, Deployment > Build Tools > Gradle > Gradle JDK そして、同梱の 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

逆の問題：Java 21 のクラスファイルを読めないほど古い Gradle wrapper で JDK 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標準ライブラリのアーティファクトが2つあり、クラスが重複しています。通常は、一方のプラグインが古い kotlin-stdlib-jdk8バージョンを読み込んでいるのが原因です。Kotlinのバージョンを1つに揃えてください。次を kotlin_version = '2.2.20' rootの build.gradle に設定し、 build.gradle (プラグインはここから読み取ります rootProject.ext)、さらにKotlin 1.xに固定しているプラグインをアップグレードしてください。必要なら、BOMを強制してください。 android/app/build.gradle:

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

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

2つのプラグインが異なるバージョンの Play Services または Firebase を持ち込んでいます。ほとんどの 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 ではエラーになるため、これを使っているプラグインにはアップデートかパッチが必要です。

AGP 9 での proguard-android.txt に関するエラー

すでに 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。Capgo CLI は 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 リリース前に。
• Dev server に接続できません：以下にバインドしてください 0.0.0.0、LAN IP を使用し、スマートフォンとコンピューターを同じネットワークにつないでおくか、ポートをフォワードする bunx cap run android --forwardPorts 5173:5173.
• 古い Android System WebView：Capacitor は android.minWebViewVersion （デフォルト 60）でチェックし、古い WebView ではエラーをログに記録します。WebView を一度も更新しないデバイスでは、モダン JavaScript でも失敗する可能性があります。 WebView バージョンチェッカープラグイン は、古い WebView を検出し、ユーザーに更新を促すことができます。
• ビルドターゲットが新しすぎる デバイスの WebView 向けです。バンドラーのターゲットを下げるか、ポリフィルを追加してください。
• 誤り 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 plugin の設定と 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);
}

を使用すると、 insetsHandling: 'css'、Capacitor は以下も注入します --safe-area-inset-* CSS 変数。これにより、古い WebView でも env() ゼロ件と報告されます。

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

アクティビティが再作成されています。確認してください android:configChanges メインアクティビティに含まれる 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 ビルドエラーの解決方法。CI マシンが原因ではなく code の問題であれば、 Capgo のビルド 適切な JDK と SDK がインストール済みの状態で Android ビルドを実行します。