Fixing “release version 17 not supported” on macOS for Spring Boot 3

If you are trying to run a Spring Boot 3 project and Maven throws release version 17 not supported, the problem is usually not your code. Most of the time, Maven is using an older JDK.

When working with modern Spring Boot 3 projects, one of the main requirements is using Java 17 or higher. This may sound simple, but in practice, it is common to run into errors when Maven is still using an older Java version, such as Java 8 or Java 11.

In this article, we will review a common case: trying to run a Java Spring Boot API and getting the following error:

Fatal error compiling: error: release version 17 not supported

Project context

Let’s assume we are working on a REST API built with:

Java 17
Spring Boot 3
Maven
PostgreSQL
Docker
macOS Intel

The application can be any typical backend project: a products API, users API, sales system, inventory system, ticketing system, reports API, or an integration service with a database.

The important point is that the project is configured to compile with Java 17.

The problem

When running the project with Maven:

mvn clean spring-boot:run

the following error appears:

[ERROR] Failed to execute goal org.apache.maven.plugins:maven-compiler-plugin:3.13.0:compile
Fatal error compiling: error: release version 17 not supported

At first, it may look like the problem is in the code or in the pom.xml. However, in many cases, the real issue is the Java version that Maven is actually using.

Checking the pom.xml file

In a Spring Boot 3 project, you will usually find a configuration like this:

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

This means the project needs to be compiled using Java 17.

You may also see a Spring Boot 3 parent like this:

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>3.3.5</version>
    <relativePath/>
</parent>

Spring Boot 3 requires Java 17 or higher. So, if Maven is running with Java 11 or Java 8, the compilation will fail.

Checking the current Java version

First, check the Java version:

java -version

A problematic output could look like this:

openjdk version "11.0.25" 2024-10-15
OpenJDK Runtime Environment Homebrew
OpenJDK 64-Bit Server VM Homebrew

In this case, the terminal is using Java 11.

Then check Maven:

mvn -version

If Maven is also using Java 11, you may see something like this:

Apache Maven 3.9.8
Java version: 11.0.25

This explains the error: the project requires Java 17, but Maven is compiling with Java 11.

Checking installed JDKs on macOS

On macOS, you can list the installed Java versions with:

/usr/libexec/java_home -V

Example output:

Matching Java Virtual Machines (2):
    11.0.25 (x86_64) "Homebrew" - "OpenJDK 11.0.25"
    1.8.371.11 (x86_64) "Oracle Corporation" - "Java"

In this case, the system only has Java 11 and Java 8 installed. Therefore, Java 17 must be installed.

Installing Java 17 with Homebrew

On macOS Intel, you can install Java 17 with Homebrew:

brew install openjdk@17

On some machines, especially with older macOS or Xcode versions, Homebrew may compile several dependencies from source. This can take a long time.

To check how long the installation has been running, you can use:

ps -axo pid,etime,command | grep -E "brew|make|python|openjdk" | grep -v grep

Example output:

33961    01:14:20 /usr/local/Homebrew/Library/Homebrew/brew.rb install openjdk@17

This means the installation has been running for approximately 1 hour, 14 minutes, and 20 seconds.

Configuring Java 17 temporarily

Once the installation finishes, configure the current terminal session to use Java 17:

export JAVA_HOME=/usr/local/opt/openjdk@17/libexec/openjdk.jdk/Contents/Home
export PATH=$JAVA_HOME/bin:$PATH
hash -r

Then verify the Java version:

java -version

You should see something similar to:

openjdk version "17..."

Also check Maven:

mvn -version

Maven should now show Java 17:

Java version: 17...

Making Java 17 permanent

To avoid repeating this configuration every time you open a new terminal, add the environment variables to your ~/.zshrc file:

echo 'export JAVA_HOME=/usr/local/opt/openjdk@17/libexec/openjdk.jdk/Contents/Home' >> ~/.zshrc
echo 'export PATH=$JAVA_HOME/bin:$PATH' >> ~/.zshrc
source ~/.zshrc

Then check again:

java -version
mvn -version

Running the API again

With Java 17 configured, go to your project directory:

cd /path/to/your/project

Run the project again:

mvn clean spring-boot:run

If everything is correct, Spring Boot should start the API on the configured port, usually:

http://localhost:8080

Testing endpoints

Some common test endpoints may be:

curl http://localhost:8080/actuator/health

Or, if your project has a custom health endpoint:

curl http://localhost:8080/api/health

If your project includes Swagger or OpenAPI, you can check the documentation at:

http://localhost:8080/swagger-ui.html

Alternative: use Docker if you do not want to install Java 17 locally

If installing Java 17 with Homebrew takes too long or fails because of dependencies, a practical alternative is running the API with Docker using an image that already includes Java 17.

For example, a simple Dockerfile could look like this:

FROM eclipse-temurin:17-jdk

WORKDIR /app

COPY . .

RUN ./mvnw clean package -DskipTests

EXPOSE 8080

CMD ["java", "-jar", "target/app.jar"]

Another option is compiling the project locally and then copying the .jar file into the container:

FROM eclipse-temurin:17-jre

WORKDIR /app

COPY target/*.jar app.jar

EXPOSE 8080

CMD ["java", "-jar", "app.jar"]

This approach avoids depending on the locally installed JDK and makes the project more portable.

Common errors

Error: release version 17 not supported

Cause: Maven is using Java 8, Java 11, or any version lower than Java 17.

Solution:

java -version
mvn -version
export JAVA_HOME=/usr/local/opt/openjdk@17/libexec/openjdk.jdk/Contents/Home
export PATH=$JAVA_HOME/bin:$PATH

Maven still uses Java 11

Run:

hash -r
mvn -version

If Maven still shows Java 11, check your ~/.zshrc, ~/.bash_profile, or any other environment configuration file.

Homebrew takes too long to install Java 17

On older macOS versions, Homebrew may compile dependencies from source. You can monitor the process with:

ps -axo pid,etime,command | grep -E "brew|make|python|openjdk" | grep -v grep

Java 17 is installed, but Maven uses Java 11

This usually happens when JAVA_HOME points to another version.

Solution:

export JAVA_HOME=/usr/local/opt/openjdk@17/libexec/openjdk.jdk/Contents/Home
export PATH=$JAVA_HOME/bin:$PATH
mvn -version

Conclusion

The error:

release version 17 not supported

does not necessarily mean your Spring Boot project is incorrectly configured. In many cases, it simply means Maven is using a Java version lower than the one required by the project.

For Spring Boot 3 projects, it is recommended to use Java 17 or higher. On macOS, you can install it with Homebrew, configure JAVA_HOME, and verify that Maven is using the correct version.

Before changing your code or modifying the pom.xml, always check:

java -version
mvn -version

Many times, the solution is in the development environment, not in the application itself.

Hope this helps you avoid wasting time debugging your Spring Boot project when the real issue is just the local Java version.

推荐订阅源

DEV Community