Skip to main content

Android - Java Versions

The Q2 DevApp targets Java 21 (javaVersion = JavaVersion.VERSION_21 in build.gradle). Building with a different JDK can produce class files compiled with an unexpected version, missing language features, or Gradle crashes.

Most developers do not need to install JDK 21 manually. Recent Android Studio releases bundle the JetBrains Runtime (JBR) 21 as their default Gradle JDK, which is fully compatible with the DevApp's Java 21 target. If you build only through Android Studio, you can stop reading this page.

The DevApp also registers the Gradle Foojay toolchain resolver, so on machines without a JDK 21 already available, Gradle automatically downloads one from Adoptium the first time you build.

This page is for developers who:

  • Build the DevApp from the command line on a machine without Android Studio.
  • Work on multiple projects that require different JDK versions and want to control them with jenv.
  • See errors like Unsupported class file major version, error: invalid source release: 21, or Could not download foojay.

Why JDK 21 specifically​

ProjectJDK declared in build files
DevApp (build.gradle)JavaVersion.VERSION_21
Q2 Mobile App (NGAM)JavaVersion.VERSION_21

JDK 21 is also a Long-Term Support (LTS) release, so it will remain supported for years.

Confirming which JDK is in use​

From the command line​

java -version

You should see something like:

openjdk version "21.0.x"

If the version is not 21.x, your shell is using a different JDK.

From Android Studio​

Navigate to: File → Project Structure → SDK Location → Gradle Settings → Gradle JDK

This is the JDK Android Studio passes to Gradle. The dropdown lets you pick the bundled JBR (default in recent releases) or any installed system JDK. Either is acceptable as long as it is version 21.

Managing multiple Java versions​

If you only ever work on the DevApp, the Android Studio bundled JBR is sufficient and you can stop reading.

If you need to switch JDKs across projects — common for developers who also work on backend Java services — use a version manager. We recommend jenv, but any equivalent tool works.

What jenv does​

  • Lets you install multiple JDKs side by side.
  • Sets a per-project JDK by reading a .java-version file in the project directory.
  • Updates JAVA_HOME automatically when you cd into a project.

Installing jenv (macOS)​

Using Homebrew:

brew install jenv

Then add jenv to your shell. For zsh (the default on modern macOS):

echo 'export PATH="$HOME/.jenv/bin:$PATH"' >> ~/.zshrc
echo 'eval "$(jenv init -)"' >> ~/.zshrc
exec "$SHELL"

For bash, replace ~/.zshrc with ~/.bash_profile.

Installing jenv (Linux)​

Follow the official instructions — the steps are similar to macOS but ~/.bashrc is the typical shell init file.

Installing jenv (Windows)​

jenv does not run natively on Windows. Use one of these alternatives:

  • scoop with the java bucket.
  • SDKMAN! running under WSL.
  • The JDK selector built into Android Studio (works fine for IDE-only workflows).

Adding a JDK to jenv​

Install JDK 21 from any of:

You can also register the JBR that ships with Android Studio. On macOS its path is /Applications/Android Studio.app/Contents/jbr/Contents/Home.

Register it with jenv:

# Path will differ depending on which JDK you installed
jenv add /Library/Java/JavaVirtualMachines/temurin-21.jdk/Contents/Home
jenv versions

Pinning JDK 21 for the DevApp​

From inside the cloned devapp-android directory:

jenv local 21

This creates a .java-version file. Anytime you cd into the project, jenv automatically uses JDK 21.

Verify:

java -version
# openjdk version "21.0.x"

Troubleshooting​

error: invalid source release: 21​

You are building with a JDK older than 21. Switch to JDK 21 with the steps above.

Unsupported class file major version 65 (or similar)​

major version 65 means JDK 21 class files. If you see this error, you are running the build with a JDK older than 21 trying to read JDK 21 output. Switch your build JDK to 21.

JAVA_HOME is not respected by Android Studio​

Android Studio does not read JAVA_HOME by default — it uses the JDK configured in File → Project Structure → SDK Location → Gradle JDK. Update that setting to point at JDK 21.

What's next​

JDK confirmed and the DevApp builds? Configure which modules it loads at Setting Up settings.json.