Resolving 'Unsupported Class File Major Version' in Ionic Capacitor Android Builds

The Problem: Gradle and JDK Version Mismatch

When building an Ionic application using Capacitor for Android, you may encounter a build failure during the Gradle sync process. The most common symptom is a terminal or IDE error stating Unsupported class file major version [number]. This happens because the Java Development Kit (JDK) used to run Gradle is newer than the version the Android Gradle Plugin (AGP) can handle, or vice versa.

The critical takeaway is that your JDK version, Gradle wrapper version, and Android Gradle Plugin (AGP) version must be aligned. If one is updated without the others, the build pipeline breaks.

Diagnostic Matrix

Use this table to identify the likely cause based on the error message appearing in your Android Studio build log or CLI output.

Error Message / Symptom	Likely Cause	Primary Check
Unsupported class file major version 61 (or higher)	JDK is too new for the current Gradle version.	Gradle JVM Settings
Minimum supported Gradle version is X.X.X	AGP version requires a newer Gradle wrapper.	gradle-wrapper.properties
Build succeeds in Android Studio but fails in CLI	JAVA_HOME environment variable mismatch.	Terminal javac -version
Persistent errors after version updates	Corrupt Gradle cache.	.gradle folder contents

Step-by-Step Resolution Path

1. Verify the IDE JVM Setting

Android Studio often uses its own embedded JDK, which may differ from your system's global Java installation. This is the most frequent source of "Major Version" errors.

1. Open Android Studio.
2. Navigate to Settings (or Preferences on macOS) > Build, Execution, Deployment > Build Tools > Gradle.
3. Locate the Gradle JDK dropdown.
4. Ensure the selected JDK matches the version required by your project (e.g., JDK 17 for recent Capacitor 5/6 projects).

2. Align Gradle Wrapper and AGP

If you updated your Android SDK or Capacitor version, you may need to bump the Gradle wrapper. The Gradle wrapper is defined in android/gradle/wrapper/gradle-wrapper.properties.

Example Configuration:
For a project using AGP 8.x, your gradle-wrapper.properties should typically point to Gradle 8.0 or higher:

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

After changing this file, run the following command in your project root to synchronize the Capacitor bridge:

npx cap sync android

3. Synchronize System Environment Variables

If you build via the command line (e.g., using ionic capacitor build android), Gradle uses the JAVA_HOME environment variable. If this points to JDK 21 while Android Studio is using JDK 17, the CLI build will fail while the IDE build succeeds.

Run this command in your terminal to check the active version:

javac -version

If the version differs from the one set in Android Studio, update your .zshrc, .bash_profile, or Windows System Environment Variables to point JAVA_HOME to the correct JDK path.

4. Clear Corrupt Caches

When switching JDK versions, Gradle may attempt to reuse cached class files that are incompatible with the new version.

1. Close Android Studio.
2. Delete the .gradle folder located in the android/ directory of your Ionic project.
3. Delete the global Gradle cache (optional, use with caution) located at ~/.gradle/caches.
4. Restart Android Studio and perform a Sync Project with Gradle Files.

Verification and Limitations

To verify the fix, execute a clean build from the terminal:

cd android && ./gradlew assembleDebug

Expected Result: The build should progress past the :app:preBuild task without throwing a major version error.

Limitations: These steps assume you are using a standard Capacitor Android project structure. If you have heavily customized your build.gradle files with third-party native plugins that require specific, older Java versions, you may be forced to use an older JDK, which may prevent you from targeting the latest Android API levels.

Rollback Procedure

If the build fails after updating the Gradle wrapper, revert the distributionUrl in gradle-wrapper.properties to the previous version and run npx cap sync android to restore the previous state.