DEV Community

Cover image for Fixing “release version 17 not supported” on macOS for Spring Boot 3
Cristian Jonhson Alvarez
Cristian Jonhson Alvarez

Posted on

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

#java #springboot #api #maven

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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>
Enter fullscreen mode Exit fullscreen mode

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>
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

In this case, the terminal is using Java 11.

Then check Maven:

mvn -version
Enter fullscreen mode Exit fullscreen mode

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

Apache Maven 3.9.8
Java version: 11.0.25
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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"
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Example output:

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

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
Enter fullscreen mode Exit fullscreen mode

Then verify the Java version:

java -version
Enter fullscreen mode Exit fullscreen mode

You should see something similar to:

openjdk version "17..."
Enter fullscreen mode Exit fullscreen mode

Also check Maven:

mvn -version
Enter fullscreen mode Exit fullscreen mode

Maven should now show Java 17:

Java version: 17...
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Then check again:

java -version
mvn -version
Enter fullscreen mode Exit fullscreen mode

Running the API again

With Java 17 configured, go to your project directory:

cd /path/to/your/project
Enter fullscreen mode Exit fullscreen mode

Run the project again:

mvn clean spring-boot:run
Enter fullscreen mode Exit fullscreen mode

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

http://localhost:8080
Enter fullscreen mode Exit fullscreen mode

Testing endpoints

Some common test endpoints may be:

curl http://localhost:8080/actuator/health
Enter fullscreen mode Exit fullscreen mode

Or, if your project has a custom health endpoint:

curl http://localhost:8080/api/health
Enter fullscreen mode Exit fullscreen mode

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

http://localhost:8080/swagger-ui.html
Enter fullscreen mode Exit fullscreen mode

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"]
Enter fullscreen mode Exit fullscreen mode

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"]
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Maven still uses Java 11

Run:

hash -r
mvn -version
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Conclusion

The error:

release version 17 not supported
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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.

Top comments (0)