{
  "$type": "site.standard.document",
  "bskyPostRef": {
    "cid": "bafyreiapxl7e5l2axwr3c5os7nc3pq3gybp2c3sblzplqyfj2qvk276x6a",
    "uri": "at://did:plc:25rdn5elo5izoxrmtis34zuk/app.bsky.feed.post/3mowbm357au22"
  },
  "coverImage": {
    "$type": "blob",
    "ref": {
      "$link": "bafkreihyirzftoeqmf6uoh2pgbka3ilpg5umhwwof2jo22iiapxnykhg7m"
    },
    "mimeType": "image/webp",
    "size": 395828
  },
  "path": "/cristian-jonhson/installing-java-17-on-macos-to-run-a-spring-boot-3-api-gle",
  "publishedAt": "2026-06-23T00:54:51.000Z",
  "site": "https://dev.to",
  "tags": [
    "java",
    "springboot",
    "api",
    "maven"
  ],
  "textContent": "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.\n\nWhen 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.\n\nIn this article, we will review a common case: trying to run a Java Spring Boot API and getting the following error:\n\n\n\n    Fatal error compiling: error: release version 17 not supported\n\n\n##  Project context\n\nLet’s assume we are working on a REST API built with:\n\n  * Java 17\n  * Spring Boot 3\n  * Maven\n  * PostgreSQL\n  * Docker\n  * macOS Intel\n\n\n\nThe 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.\n\nThe important point is that the project is configured to compile with Java 17.\n\n##  The problem\n\nWhen running the project with Maven:\n\n\n\n    mvn clean spring-boot:run\n\n\nthe following error appears:\n\n\n\n    [ERROR] Failed to execute goal org.apache.maven.plugins:maven-compiler-plugin:3.13.0:compile\n    Fatal error compiling: error: release version 17 not supported\n\n\nAt 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.\n\n##  Checking the pom.xml file\n\nIn a Spring Boot 3 project, you will usually find a configuration like this:\n\n\n\n    <properties>\n        <java.version>17</java.version>\n    </properties>\n\n\nThis means the project needs to be compiled using Java 17.\n\nYou may also see a Spring Boot 3 parent like this:\n\n\n\n    <parent>\n        <groupId>org.springframework.boot</groupId>\n        <artifactId>spring-boot-starter-parent</artifactId>\n        <version>3.3.5</version>\n        <relativePath/>\n    </parent>\n\n\nSpring Boot 3 requires Java 17 or higher. So, if Maven is running with Java 11 or Java 8, the compilation will fail.\n\n##  Checking the current Java version\n\nFirst, check the Java version:\n\n\n\n    java -version\n\n\nA problematic output could look like this:\n\n\n\n    openjdk version \"11.0.25\" 2024-10-15\n    OpenJDK Runtime Environment Homebrew\n    OpenJDK 64-Bit Server VM Homebrew\n\n\nIn this case, the terminal is using Java 11.\n\nThen check Maven:\n\n\n\n    mvn -version\n\n\nIf Maven is also using Java 11, you may see something like this:\n\n\n\n    Apache Maven 3.9.8\n    Java version: 11.0.25\n\n\nThis explains the error: the project requires Java 17, but Maven is compiling with Java 11.\n\n##  Checking installed JDKs on macOS\n\nOn macOS, you can list the installed Java versions with:\n\n\n\n    /usr/libexec/java_home -V\n\n\nExample output:\n\n\n\n    Matching Java Virtual Machines (2):\n        11.0.25 (x86_64) \"Homebrew\" - \"OpenJDK 11.0.25\"\n        1.8.371.11 (x86_64) \"Oracle Corporation\" - \"Java\"\n\n\nIn this case, the system only has Java 11 and Java 8 installed. Therefore, Java 17 must be installed.\n\n##  Installing Java 17 with Homebrew\n\nOn macOS Intel, you can install Java 17 with Homebrew:\n\n\n\n    brew install openjdk@17\n\n\nOn some machines, especially with older macOS or Xcode versions, Homebrew may compile several dependencies from source. This can take a long time.\n\nTo check how long the installation has been running, you can use:\n\n\n\n    ps -axo pid,etime,command | grep -E \"brew|make|python|openjdk\" | grep -v grep\n\n\nExample output:\n\n\n\n    33961    01:14:20 /usr/local/Homebrew/Library/Homebrew/brew.rb install openjdk@17\n\n\nThis means the installation has been running for approximately **1 hour, 14 minutes, and 20 seconds**.\n\n##  Configuring Java 17 temporarily\n\nOnce the installation finishes, configure the current terminal session to use Java 17:\n\n\n\n    export JAVA_HOME=/usr/local/opt/openjdk@17/libexec/openjdk.jdk/Contents/Home\n    export PATH=$JAVA_HOME/bin:$PATH\n    hash -r\n\n\nThen verify the Java version:\n\n\n\n    java -version\n\n\nYou should see something similar to:\n\n\n\n    openjdk version \"17...\"\n\n\nAlso check Maven:\n\n\n\n    mvn -version\n\n\nMaven should now show Java 17:\n\n\n\n    Java version: 17...\n\n\n##  Making Java 17 permanent\n\nTo avoid repeating this configuration every time you open a new terminal, add the environment variables to your `~/.zshrc` file:\n\n\n\n    echo 'export JAVA_HOME=/usr/local/opt/openjdk@17/libexec/openjdk.jdk/Contents/Home' >> ~/.zshrc\n    echo 'export PATH=$JAVA_HOME/bin:$PATH' >> ~/.zshrc\n    source ~/.zshrc\n\n\nThen check again:\n\n\n\n    java -version\n    mvn -version\n\n\n##  Running the API again\n\nWith Java 17 configured, go to your project directory:\n\n\n\n    cd /path/to/your/project\n\n\nRun the project again:\n\n\n\n    mvn clean spring-boot:run\n\n\nIf everything is correct, Spring Boot should start the API on the configured port, usually:\n\n\n\n    http://localhost:8080\n\n\n##  Testing endpoints\n\nSome common test endpoints may be:\n\n\n\n    curl http://localhost:8080/actuator/health\n\n\nOr, if your project has a custom health endpoint:\n\n\n\n    curl http://localhost:8080/api/health\n\n\nIf your project includes Swagger or OpenAPI, you can check the documentation at:\n\n\n\n    http://localhost:8080/swagger-ui.html\n\n\n##  Alternative: use Docker if you do not want to install Java 17 locally\n\nIf 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.\n\nFor example, a simple `Dockerfile` could look like this:\n\n\n\n    FROM eclipse-temurin:17-jdk\n\n    WORKDIR /app\n\n    COPY . .\n\n    RUN ./mvnw clean package -DskipTests\n\n    EXPOSE 8080\n\n    CMD [\"java\", \"-jar\", \"target/app.jar\"]\n\n\nAnother option is compiling the project locally and then copying the `.jar` file into the container:\n\n\n\n    FROM eclipse-temurin:17-jre\n\n    WORKDIR /app\n\n    COPY target/*.jar app.jar\n\n    EXPOSE 8080\n\n    CMD [\"java\", \"-jar\", \"app.jar\"]\n\n\nThis approach avoids depending on the locally installed JDK and makes the project more portable.\n\n##  Common errors\n\n###  Error: release version 17 not supported\n\nCause: Maven is using Java 8, Java 11, or any version lower than Java 17.\n\nSolution:\n\n\n\n    java -version\n    mvn -version\n    export JAVA_HOME=/usr/local/opt/openjdk@17/libexec/openjdk.jdk/Contents/Home\n    export PATH=$JAVA_HOME/bin:$PATH\n\n\n###  Maven still uses Java 11\n\nRun:\n\n\n\n    hash -r\n    mvn -version\n\n\nIf Maven still shows Java 11, check your `~/.zshrc`, `~/.bash_profile`, or any other environment configuration file.\n\n###  Homebrew takes too long to install Java 17\n\nOn older macOS versions, Homebrew may compile dependencies from source. You can monitor the process with:\n\n\n\n    ps -axo pid,etime,command | grep -E \"brew|make|python|openjdk\" | grep -v grep\n\n\n###  Java 17 is installed, but Maven uses Java 11\n\nThis usually happens when `JAVA_HOME` points to another version.\n\nSolution:\n\n\n\n    export JAVA_HOME=/usr/local/opt/openjdk@17/libexec/openjdk.jdk/Contents/Home\n    export PATH=$JAVA_HOME/bin:$PATH\n    mvn -version\n\n\n##  Conclusion\n\nThe error:\n\n\n\n    release version 17 not supported\n\n\ndoes 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.\n\nFor **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.\n\nBefore changing your code or modifying the `pom.xml`, always check:\n\n\n\n    java -version\n    mvn -version\n\n\nMany times, the solution is in the development environment, not in the application itself.\n\nHope this helps you avoid wasting time debugging your Spring Boot project when the real issue is just the local Java version.",
  "title": "Fixing “release version 17 not supported” on macOS for Spring Boot 3"
}