Maven Toolchains "Cannot find matching toolchain" - Fix in CI

The maven-toolchains-plugin required a JDK toolchain but found no matching entry in toolchains.xml. The file is missing, or it has no JDK definition matching the requested version on the runner.

What this error means

The build fails early with Cannot find matching toolchain definitions for the following toolchain types: jdk [version:17], and the toolchains plugin reports no usable toolchain.

mvn output

[ERROR] Failed to execute goal
org.apache.maven.plugins:maven-toolchains-plugin:3.2.0:toolchain
(default) on project app: Cannot find matching toolchain definitions
for the following toolchain types: jdk [ provides {version=17} ]

Common causes

toolchains.xml missing on the runner

CI runners do not ship a ~/.m2/toolchains.xml. With the toolchains plugin required, there is no JDK definition to match.

No entry matching the requested version

toolchains.xml exists but has no <jdk> whose <version> matches what the plugin requested, so no toolchain is selected.

How to fix it

Generate toolchains.xml from the runner JDK

setup-java can write a matching toolchains.xml for the JDK it installs.

.github/workflows/ci.yml

- uses: actions/setup-java@v4
  with:
    distribution: temurin
    java-version: '17'   # also writes ~/.m2/toolchains.xml entry for jdk 17

Provide a toolchains.xml entry

Write a toolchains.xml whose JDK version and path match the installed JDK.

~/.m2/toolchains.xml

<toolchains>
  <toolchain>
    <type>jdk</type>
    <provides><version>17</version></provides>
    <configuration><jdkHome>${env.JAVA_HOME}</jdkHome></configuration>
  </toolchain>
</toolchains>

How to prevent it

Generate toolchains.xml from setup-java (or template it) so a JDK entry always matches the version the toolchains plugin requests.