Android Studio「incompatible version of the Android Gradle plugin」の解決方法

「incompatible version of the Android Gradle plugin」とは

「incompatible version of the Android Gradle plugin」は、
使用しているAndroid Gradle Pluginのバージョンが、
現在のAndroid StudioやGradleなどと互換性がない場合に表示されるエラーです。

エラーメッセージには、
使用しているAndroid Gradle Pluginのバージョンや、
対応しているバージョンの範囲が表示される場合があります。

この場合は、
Android Gradle Pluginだけを見るのではなく、
Android Studio、
Gradle、
JDKなどのバージョンも含めて確認する必要があります。

主な原因

Android Studioで
「incompatible version of the Android Gradle plugin」が発生する主な原因には、
次のようなものがあります。

• Android Gradle Pluginのバージョンが古い
• Android Gradle Pluginのバージョンが新しすぎる
• Android StudioとAndroid Gradle Pluginの組み合わせが合っていない
• GradleとAndroid Gradle Pluginの組み合わせが合っていない
• 使用しているJDKが対応していない
• Android Studioだけを更新した
• Android Gradle Pluginだけを更新した
• Gradle Wrapperだけを更新した
• 古いAndroidプロジェクトを新しいAndroid Studioで開いた
• 複数のプラグインや設定ファイルで異なるバージョンが指定されている

Android Gradle Pluginのバージョンを確認する

最初に、
プロジェクトで使用しているAndroid Gradle Pluginのバージョンを確認します。

プロジェクトによっては、
次のように設定されています。

plugins {
    id("com.android.application") version "8.5.0" apply false
}

また、
古いプロジェクトでは次のように設定されている場合があります。

classpath 'com.android.tools.build:gradle:8.5.0'

ここで指定されているバージョンが、
現在のAndroid StudioやGradleと互換性があるか確認します。

Android Studioとの互換性を確認する

Android Gradle Pluginは、
すべてのAndroid Studioバージョンで使用できるわけではありません。

Android Studioが古すぎる場合、
新しいAndroid Gradle Pluginを使用できないことがあります。

逆に、
非常に古いAndroid Gradle Pluginを、
新しいAndroid Studioで使用した場合に、
更新を求められたり互換性に関する警告やエラーが表示されたりすることがあります。

Android Studioを更新した直後にエラーが発生した場合は、
プロジェクトで使用しているAndroid Gradle Pluginのバージョンを確認します。

Gradleのバージョンを確認する

Android Gradle Pluginには、
対応するGradleのバージョンがあります。

Gradleのバージョンは、
通常次のファイルで確認できます。

gradle/wrapper/gradle-wrapper.properties

ファイル内の
distributionUrl
を確認します。

distributionUrl=https\://services.gradle.org/distributions/gradle-8.7-bin.zip

Android Gradle PluginとGradleの組み合わせが合っていない場合は、
どちらかのバージョンを対応するものへ変更します。

GradleとAndroid Gradle Pluginの組み合わせを確認する

Android Gradle PluginとGradleは、
任意のバージョンを自由に組み合わせられるわけではありません。

Android Gradle Pluginのバージョンによって、
必要なGradleの最低バージョンや対応範囲が異なります。

Android Gradle Pluginを更新した後にエラーが発生した場合は、
Gradle Wrapperのバージョンが古いままになっていないか確認します。

Gradleだけを更新した場合も、
Android Gradle Pluginが新しいGradleに対応していない可能性があります。

Android Gradle Pluginを更新する

Android Gradle Pluginが古すぎることが原因の場合は、
対応するバージョンへ更新します。

pluginsブロックを使用している場合は、
例えば次のようにバージョンを変更します。

plugins {
    id("com.android.application") version "8.5.0" apply false
}

古い形式のプロジェクトでは、
次のようなclasspathのバージョンを変更します。

classpath 'com.android.tools.build:gradle:8.5.0'

更新する場合は、
同時にGradleの対応バージョンも確認します。

Android Gradle Pluginを下げる

Android Gradle Pluginが新しすぎることが原因の場合は、
Android StudioやGradleに対応した以前のバージョンへ戻すことで解決する場合があります。

特にAndroid Gradle Pluginだけを手動で新しいバージョンへ変更した直後に
エラーが発生した場合は、
変更前のバージョンとの違いを確認します。

Android Studioを更新できない環境では、
Android Gradle Plugin側を対応するバージョンへ下げる方法もあります。

Gradle Wrapperを更新する

Android Gradle Pluginに対してGradleが古い場合は、
Gradle Wrapperを更新します。

gradle/wrapper/gradle-wrapper.properties
の
distributionUrl
を確認し、
対応するGradleバージョンへ変更します。

例えば、Gradle 8.7へ変更する場合は次のようにします。

distributionUrl=https\://services.gradle.org/distributions/gradle-8.7-bin.zip

変更後はGradle Syncを再実行します。

Gradleを必要以上に新しくしない

Gradleを最新版へ更新すると、
使用しているAndroid Gradle Pluginが対応していない場合があります。

Android Gradle Pluginに対してGradleが新しすぎる場合は、
対応しているGradleバージョンへ戻す必要があります。

そのため、
Gradleを変更するときは、
Android Gradle Pluginとの対応関係を確認してから変更します。

JDKのバージョンを確認する

Android Gradle PluginやGradleのバージョンを変更すると、
使用するJDKの要件も変わる場合があります。

Android Gradle PluginとGradleの組み合わせを修正した後に、
JDK関連のエラーが発生する場合は、
使用しているJDKのバージョンを確認します。

Android Studioでは、
Gradleで使用するJDKを設定できます。

Gradle JDKを確認する

Android Studioで選択されているGradle JDKが、
使用しているAndroid Gradle PluginやGradleに対応していない場合、
ビルドやGradle Syncが失敗することがあります。

Android Studioの設定から、
Gradleが使用するJDKを確認します。

Android Studioに付属するJDKを使用することで、
環境による差を減らせる場合もあります。

Android Studioだけを更新した場合

Android Studioだけを更新し、
プロジェクトのGradleやAndroid Gradle Pluginを変更していない場合でも、
古いプロジェクトに対して更新を求められることがあります。

この場合は、
Android Studioの更新後に表示された案内やエラー内容を確認し、
Android Gradle PluginとGradleを対応する組み合わせへ変更します。

Android Gradle Pluginだけを更新した場合

Android Gradle Pluginだけを新しくした場合は、
Gradle WrapperやJDKが古いままになっている可能性があります。

特に次のようなエラーが続けて表示される場合があります。

Minimum supported Gradle version is ...

この場合は、
Android Gradle Pluginが要求するGradleバージョンを確認し、
Gradle Wrapperも合わせて変更します。

Gradle Wrapperだけを更新した場合

Gradle Wrapperだけを新しくすると、
Android Gradle PluginがそのGradleバージョンに対応していない場合があります。

Gradleを更新した直後に互換性エラーが発生した場合は、
Android Gradle Pluginのバージョンも確認します。

古いプロジェクトを新しいAndroid Studioで開いた場合

古いAndroidプロジェクトでは、
Android Gradle Plugin、
Gradle、
JDKなどが古い構成になっている場合があります。

このようなプロジェクトを新しいAndroid Studioで開くと、
複数の互換性エラーが順番に発生する場合があります。

一度にすべてを最新版へ変更するのではなく、
Android Gradle Plugin、
Gradle、
JDKの対応関係を確認しながら順番に更新します。

Version Catalogを確認する

新しい形式のAndroidプロジェクトでは、
プラグインのバージョンがVersion Catalogで管理されている場合があります。

例えば、
次のようなファイルを確認します。

gradle/libs.versions.toml

Android Gradle Pluginのバージョンがこのファイルに記載されている場合は、
build.gradleやbuild.gradle.ktsだけを変更しても
バージョンが変わらない場合があります。

複数の設定場所を確認する

プロジェクトによっては、
Android Gradle Pluginのバージョンが複数の場所で管理されている場合があります。

例えば、
次のような場所を確認します。

• build.gradle
• build.gradle.kts
• settings.gradle
• settings.gradle.kts
• gradle/libs.versions.toml

変更したつもりでも、
実際には別の設定ファイルからバージョンが読み込まれている場合があります。

Gradle Syncを再実行する

Android Gradle PluginやGradleのバージョンを変更した後は、
Gradle Syncを再実行します。

Android Studioから
Sync Project with Gradle Files
などを実行します。

必要なGradleやプラグインがまだ取得されていない場合は、
Sync時にダウンロードされることがあります。

インターネット接続を確認する

Android Gradle PluginやGradleのバージョンを変更した場合、
必要なファイルをインターネットから取得することがあります。

ネットワーク接続に問題があると、
互換性のあるバージョンへ変更していても、
プラグインやGradleを取得できず別のエラーになる場合があります。

更新後にダウンロード関連のエラーが表示された場合は、
インターネット接続も確認します。

Clean Projectを実行する

バージョンを変更した後も古いビルド情報が残っている場合は、
Clean Projectを実行すると改善することがあります。

Android StudioのBuildメニューなどから
Clean Project
を実行し、
その後Gradle SyncやRebuild Projectを実行します。

Android Studioを再起動する

GradleやAndroid Gradle Pluginの設定を変更しても
エラー表示が変わらない場合は、
Android Studioを再起動してからGradle Syncを再実行します。

IDE側に以前の状態が残っている場合、
再起動によって変更内容が反映されることがあります。

エラー別の確認ポイント

Android Gradle PluginやGradleに関するエラーによって、
確認すべき場所をある程度絞り込むことができます。

解決しない場合の確認手順

原因が分からない場合は、
次の順番で確認すると問題を切り分けやすくなります。

1. 「incompatible version of the Android Gradle plugin」のエラー全文を確認する
2. 使用しているAndroid Gradle Pluginのバージョンを確認する
3. Android Studioのバージョンとの互換性を確認する
4. gradle-wrapper.propertiesでGradleのバージョンを確認する
5. Android Gradle PluginとGradleの対応関係を確認する
6. 必要に応じてAndroid Gradle Pluginを更新または変更する
7. 必要に応じてGradle Wrapperを対応するバージョンへ変更する
8. JDKのバージョンを確認する
9. Gradle JDKの設定を確認する
10. Version Catalogを使用している場合はlibs.versions.tomlを確認する
11. 複数の設定ファイルで異なるバージョンが指定されていないか確認する
12. Gradle Syncを再実行する
13. 必要に応じてClean Projectを実行する
14. 必要に応じてAndroid Studioを再起動する

まとめ

Android Studioの
「incompatible version of the Android Gradle plugin」
は、
Android Gradle PluginとAndroid Studio、
Gradle、
JDKなどのバージョンに互換性がない場合に表示されるエラーです。

特にAndroid StudioやAndroid Gradle Pluginを更新した場合や、
古いAndroidプロジェクトを新しい環境で開いた場合に発生することがあります。

まずAndroid Gradle Pluginのバージョンを確認し、
次に
gradle/wrapper/gradle-wrapper.properties
でGradleのバージョンを確認します。

そのうえで、
Android Studio、
Android Gradle Plugin、
Gradle、
JDKの対応関係を確認し、
互換性のある組み合わせへ変更してからGradle Syncを再実行すると、
原因を効率よく切り分けることができます。