Introduction

In a Maven-based Spring or Spring Boot project, the Java version should be declared in pom.xml so compilation is consistent across local machines, CI, and packaging. In modern Maven builds, the cleanest approach is usually to set the intended Java version in properties and compile with the Maven compiler plugin using release.

The important idea is that build metadata and the real installed JDK must agree. Declaring a Java version in pom.xml expresses intent, but Maven still runs on the JDK that is actually installed in the environment.

The Common Spring Boot Convention

In Spring Boot projects, it is common to declare a java.version property.

<properties>
    <java.version>17</java.version>
</properties>

This makes the intended baseline obvious and is commonly used by Boot-oriented build conventions.

But the property alone is not the whole story. The actual compiler behavior still depends on the Maven compiler plugin settings.

Use the Maven Compiler Plugin with release

A modern Maven setup usually prefers release over separate source and target values.

1<properties>
2    <java.version>17</java.version>
3    <maven.compiler.release>${java.version}</maven.compiler.release>
4</properties>

Or explicitly inside the plugin:

1<build>
2    <plugins>
3        <plugin>
4            <groupId>org.apache.maven.plugins</groupId>
5            <artifactId>maven-compiler-plugin</artifactId>
6            <version>3.11.0</version>
7            <configuration>
8                <release>17</release>
9            </configuration>
10        </plugin>
11    </plugins>
12</build>

Using release is usually clearer because it ties compilation to the intended Java platform level more directly than just source-syntax and bytecode-target settings.

A Practical Spring Boot Example

1<project>
2    <modelVersion>4.0.0</modelVersion>
3
4    <parent>
5        <groupId>org.springframework.boot</groupId>
6        <artifactId>spring-boot-starter-parent</artifactId>
7        <version>3.3.0</version>
8        <relativePath/>
9    </parent>
10
11    <properties>
12        <java.version>17</java.version>
13        <maven.compiler.release>${java.version}</maven.compiler.release>
14    </properties>
15
16    <dependencies>
17        <dependency>
18            <groupId>org.springframework.boot</groupId>
19            <artifactId>spring-boot-starter-web</artifactId>
20        </dependency>
21    </dependencies>
22</project>

The same overall pattern works even if the exact Boot version or Java baseline is different in your project.

Why release Is Usually Better Than Only source and target

Older examples often show:

<maven.compiler.source>17</maven.compiler.source>
<maven.compiler.target>17</maven.compiler.target>

That can work, but release is generally the clearer modern setting because it expresses "compile against this Java platform level" in one place.

If you are maintaining an older build, you may still see source and target. For new or cleaned-up builds, release is usually the better default.

The Installed JDK Still Matters

A correct pom.xml does not install or switch Java for you. Maven will still run using the JDK available in your shell, CI agent, or toolchain configuration.

So in practice, all of these must line up:

• the Java version declared in pom.xml
• the JDK Maven is actually using
• the Java version supported by your Spring or Spring Boot line

If they do not agree, the XML may look correct while the build still fails.

Verify the Effective Environment

When something seems inconsistent, check what Maven is really using.

mvn -version
java -version

Those commands are often more informative than staring at the pom.xml, because they show the actual JDK behind the build.

Toolchains Are the Next Step for Strict Environments

If you need stricter control across machines, Maven Toolchains can help ensure the build uses the intended JDK instead of whatever happens to be on the shell path. That is especially useful in larger teams and CI environments.

But even without toolchains, the first step is still the same: declare the version clearly and keep the environment aligned with it.

Common Pitfalls

The biggest mistake is setting <java.version> and assuming that alone controls compilation even when the compiler plugin is not aligned. Another is copying old source and target examples without considering whether release is the cleaner modern choice. Developers also often declare one Java version in pom.xml while CI is actually running Maven on a different JDK. Finally, Spring or Spring Boot compatibility still matters, so the selected Java version must match the framework line you are actually using.

Summary

• Declare the intended Java version in pom.xml properties.
• Use the Maven compiler plugin with release for the actual compilation target.
• Keep the declared Java version and the installed JDK aligned.
• 'release is usually preferable to only source and target.'
• Verify the real build environment with mvn -version when behavior seems inconsistent.