DEV Community

Cover image for IntelliJ Java Version Mismatch: Project SDK, Gradle JVM, and JAVA_HOME Explained
nocklock
nocklock

Posted on

IntelliJ Java Version Mismatch: Project SDK, Gradle JVM, and JAVA_HOME Explained

#java #intellij #gradle #springboot

IntelliJ Java Version Mismatch: Project SDK, Gradle JVM, and JAVA_HOME Explained

I recently set up a new development laptop from scratch.

JDK 17 was installed.

The terminal looked fine.

java -version
Enter fullscreen mode Exit fullscreen mode

It returned the version I expected.

That should mean my Java environment is ready, right?

Not necessarily.

While setting up IntelliJ again, I was reminded of something that is easy to forget once a development machine has been configured for years:

The Java version shown in your terminal is not always the Java version IntelliJ or Gradle is actually using.

There are several places where Java versions can be configured, and they do not automatically mean the same thing.

1. Start with the Java version your terminal is using

The first thing I check is still the simplest one.

java -version
Enter fullscreen mode Exit fullscreen mode

I also check the compiler version.

javac -version
Enter fullscreen mode Exit fullscreen mode

On Windows, you can also inspect JAVA_HOME.

Command Prompt 

echo %JAVA_HOME%
Enter fullscreen mode Exit fullscreen mode

PowerShell 

$env:JAVA_HOME
Enter fullscreen mode Exit fullscreen mode

And if multiple JDKs have been installed before, it is useful to check which Java executable is actually being resolved.

Command Prompt 

where java
Enter fullscreen mode Exit fullscreen mode

PowerShell 

Get-Command java
Enter fullscreen mode Exit fullscreen mode

This tells you what your terminal sees.

But this is only the first layer.

2. Check IntelliJ Project SDK

In IntelliJ IDEA, check:

File
→ Project Structure
→ Project
→ SDK
Enter fullscreen mode Exit fullscreen mode

This is the JDK configured for the project inside IntelliJ.

A common assumption is:

java -version = 17
Enter fullscreen mode Exit fullscreen mode

therefore:

IntelliJ Project SDK = 17
Enter fullscreen mode Exit fullscreen mode

But those are separate settings.

Your system may use one JDK while IntelliJ points to another.

That is why checking only the terminal can be misleading.

3. Do not forget the Gradle JVM

For Gradle projects, there is another setting that is easy to overlook.

Settings
→ Build, Execution, Deployment
→ Build Tools
→ Gradle
→ Gradle JVM
Enter fullscreen mode Exit fullscreen mode

The important distinction is:

Project SDK
→ JDK configured for the IntelliJ project

Gradle JVM
→ JVM used to run Gradle
Enter fullscreen mode Exit fullscreen mode

So this configuration is completely possible:

System Java: 17
Project SDK: 17
Gradle JVM: 11
Enter fullscreen mode Exit fullscreen mode

At first glance, everything looks like a Java 17 project.

Then the Gradle build starts behaving differently.

That is usually the point where the setup becomes confusing.

Project SDK and Gradle JVM are related, but they are not the same setting.

4. Check what Gradle is actually running with

If the project uses the Gradle Wrapper, you can check it directly.

Command Prompt 

gradlew.bat --version
Enter fullscreen mode Exit fullscreen mode

PowerShell 

.\gradlew.bat --version
Enter fullscreen mode Exit fullscreen mode

The output includes the JVM Gradle is running with.

This is useful when IntelliJ looks correct but the build is still complaining about Java versions.

Instead of changing random settings, you can verify which JVM each layer is actually using.

5. Your project may define its own Java requirement

The project itself can also specify the Java version.

For example, using a Gradle Java Toolchain:

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(17)
    }
}
Enter fullscreen mode Exit fullscreen mode

Older or existing projects may also contain something like:

sourceCompatibility = '17'
Enter fullscreen mode Exit fullscreen mode

The exact configuration varies between projects.

The important point is that your machine configuration is not the only thing that matters.

The project may have its own Java requirement too.

Why Java version problems become confusing

The problem is not simply "Java 17 vs Java 21."

The confusing part is that Java can appear in several places:

Windows Java
     ↓
JAVA_HOME / PATH

IntelliJ
     ↓
Project SDK

Gradle
     ↓
Gradle JVM

Project
     ↓
build.gradle / toolchain
Enter fullscreen mode Exit fullscreen mode

These settings are related.

But they are not identical.

That is the part I had almost stopped thinking about because my previous development machine had already been configured for years.

On a new laptop, all of those invisible assumptions become visible again.

When I see a Java version error, this is what I check first

Situation First things to check
Terminal and IntelliJ show different Java versions JAVA_HOME, PATH, Project SDK
Gradle build complains about Java version Gradle JVM, gradlew --version
invalid source release Project SDK, Gradle JVM, project Java configuration
A dependency requires a newer JVM Gradle JVM and runtime JVM
Project worked on the old machine but not the new one JDK, environment variables, Gradle JVM, project configuration

The exact error may be different.

But checking which layer is actually using which Java version is usually more useful than immediately copying the first fix from a search result.

The setup order I use on a new machine

For my new laptop, I kept it simple:

Install JDK
↓
Check java -version
↓
Install IntelliJ
↓
Check Project SDK
↓
Check Gradle JVM
↓
Run an existing project
Enter fullscreen mode Exit fullscreen mode

That last step matters the most.

A development environment is not really finished just because the IDE opens.

For me, it is finished when an existing project can build and run again.

Setting up a new machine reminded me that many things we think of as "automatic" are really just configuration that was done a long time ago.

Once you rebuild everything from zero, you start seeing those dependencies again.

And Java version configuration is a good example.

Shipping the project after the environment works

Getting the environment running is only the first step.

Actually shipping a Spring Boot project comes with a different set of checks:

  • configuration
  • deployment
  • verification
  • release decisions

I put the basic version of that workflow here:

Ship Your Spring Boot MVP — Free Edition

Get the free Spring Boot MVP checklist on GitHub

If you want the full checklist and release workflow:

Ship Your Spring Boot MVP — Full Edition

Get the Full Edition

If you're setting up Java on a new machine, the main thing I would remember is this:

Don't ask only, "Which Java version did I install?"

Ask, "Which Java version is each part of my development environment actually using?"

That question usually makes the problem much easier to trace.

Top comments (0)