Android Gradleプラグインの互換性エラーと解決方法

このエラーについて

「The project is using an incompatible version of the Android Gradle plugin」というエラーは、プロジェクトで使用されているAndroid Gradleプラグイン（AGP）のバージョンが、現在のAndroid Studioバージョンと互換性がない場合に発生します。

問題の詳細

このエラーは、以下のようなケースで発生します：

GitHubなどからインポートしたプロジェクトのAGPバージョンが、ローカルのAndroid Studioバージョンと異なる場合
Android Studioをダウングレードした後、プロジェクトのAGPバージョンが新しすぎる場合
Android StudioをアップデートせずにプロジェクトのAGPバージョンだけを更新した場合

エラーメッセージ例：

The project is using an incompatible version (AGP 8.4.0) of the Android Gradle plugin. 
Latest supported version is AGP 8.2.2

解決方法

方法1: AGPバージョンの変更（推奨）

プロジェクトで使用されているAGPバージョンを、Android Studioがサポートしているバージョンに変更します。

従来のbuild.gradleファイルの場合

プロジェクトレベルのbuild.gradleファイルを開き、classpathのバージョンを変更します：

groovy

buildscript {
    dependencies {
        // サポートされているバージョンに変更（例：7.2.1）
        classpath 'com.android.tools.build:gradle:7.2.1'
        // その他の依存関係...
    }
}

libs.versions.tomlを使用している場合

プロジェクトビューでgradle/libs.versions.tomlファイルを開く
agpのバージョンをサポートされているバージョンに変更：

toml

[versions]
agp = "8.2.2"  # エラーメッセージで示されたバージョンに変更

[plugins]
android-application = { id = "com.android.application", version.ref = "agp" }
android-library = { id = "com.android.library", version.ref = "agp" }

Kotlin DSLを使用している場合

kotlin

plugins {
    id("com.android.application") version "8.3.1"
    // または
    alias(libs.plugins.android.application) version("8.3.1")
}

バージョン確認

使用可能なAGPバージョンは、Android Developer公式サイトで確認できます。

方法2: Android Studioのアップデート

Android Studioを最新バージョンに更新することで、新しいAGPバージョンをサポートできます。

Android Studioで更新を確認：
- Windows/Linux: File → Settings → Appearance & Behavior → System Settings → Updates
- Mac: Android Studio → Check for Updates
利用可能な更新をインストール
Android Studioを再起動
プロジェクトのGradle syncを実行

注意

Android Studioのアップデートは、大規模な変更を伴う場合があります。重要なプロジェクトの場合は、バックアップを取ってから実行してください。

方法3: プロジェクト構造設定からの変更

File → Project Structureを開く
左ペインでProjectを選択
Android Gradle Plugin Versionをサポートされているバージョンに変更
Gradle Versionも必要に応じて調整
OKをクリックして適用

互換性テーブル

以下は主要なAndroid StudioバージョンとAGPの互換性の目安です：

Android Studioバージョン	サポートされるAGPバージョン
Android Studio Hedgehog	8.2.xまで
Android Studio Iguana	8.3.xまで
Android Studio Jellyfish	8.4.xまで
最新のKoalaバージョン	最新のAGPをサポート

詳細な互換性表を見る

正確な互換性情報は、Android StudioとAGPの互換性表を参照してください。

トラブルシューティング

複数箇所のバージョン設定を確認

プロジェクト内の以下のファイルでAGPバージョンが設定されていないか確認してください：

build.gradle（プロジェクトレベル）
build.gradle.kts（プロジェクトレベル）
gradle.properties
settings.gradle / settings.gradle.kts
libs.versions.toml

キャッシュのクリア

変更を反映しない場合は、Gradleキャッシュをクリアします：

File → Invalid Caches / Restart
「Invalidate and Restart」を選択
またはターミナルで：./gradlew cleanBuildCache

予防策

プロジェクトを共有する前に：AGPバージョンを明確にドキュメント化する
チーム開発時：.ideaフォルダをバージョン管理に含めない
定期的に：Android StudioとAGPの互換性を確認する

まとめ

AGPの互換性エラーは、以下のいずれかの方法で解決できます：

AGPバージョンのダウングレード（プロジェクトの変更）
Android Studioのアップグレード（開発環境の変更）
プロジェクト設定の調整

プロジェクトの要件やチームの事情に応じて、適切な解決方法を選択してください。新しい機能が必要ない場合はAGPバージョンのダウングレードが、最新の機能が必要な場合はAndroid Studioのアップグレードが推奨されます。

関連記事

Android Gradleプラグインの互換性エラーと解決方法 ​

問題の詳細 ​

解決方法 ​

方法1: AGPバージョンの変更（推奨） ​

従来のbuild.gradleファイルの場合 ​

libs.versions.tomlを使用している場合 ​

Kotlin DSLを使用している場合 ​

方法2: Android Studioのアップデート ​

方法3: プロジェクト構造設定からの変更 ​

互換性テーブル ​

トラブルシューティング ​

複数箇所のバージョン設定を確認 ​

キャッシュのクリア ​

予防策 ​

まとめ ​