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

By Daniel Zoghalchali·Latchkey

The maven-toolchains-plugin was asked to select a JDK by version, but there is no matching entry in toolchains.xml. Either the file is missing in CI or it has no <jdk> for the version requested.

What this error means

The build fails early with Cannot find matching toolchain definitions for the following toolchain types: jdk and the requested version (e.g. {version=21}). The plugin will not guess a JDK; it needs an explicit definition.

mvn output

[ERROR] Failed to execute goal
org.apache.maven.plugins:maven-toolchains-plugin:3.1.0:toolchain ...
Cannot find matching toolchain definitions for the following toolchain types:
jdk [ provides {version=21} ]

Diagnose it: which JDK is the build actually using?

JVM builds resolve a toolchain from several sources, and the one on PATH is often not the one compiling your code. A version mismatch surfaces as an unsupported class file version rather than as a toolchain error.

Terminal

java -version 2>&1
echo "JAVA_HOME=$JAVA_HOME"
./gradlew -q javaToolchains 2>/dev/null || mvn -v

# class file 65 = Java 21, 61 = Java 17, 55 = Java 11
javap -verbose <SomeClass>.class | grep "major version"

Common causes

toolchains.xml missing on the runner

Maven reads ~/.m2/toolchains.xml. In a fresh CI environment that file does not exist, so the plugin finds no JDK definitions at all.

No <jdk> entry for the requested version

The file exists but lacks a <jdk> whose <version> matches what the plugin requests, so there is no match to select.

How to fix it

Generate toolchains.xml in CI

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

.github/workflows/ci.yml

- uses: actions/setup-java@v4
  with:
    distribution: temurin
    java-version: '21'
    # this populates ~/.m2/toolchains.xml with a matching <jdk>

Provide a matching JDK definition

Ensure a <jdk> entry matches the version the plugin requests.

~/.m2/toolchains.xml

<toolchains>
  <toolchain>
    <type>jdk</type>
    <provides><version>21</version></provides>
    <configuration><jdkHome>/opt/jdk-21</jdkHome></configuration>
  </toolchain>
</toolchains>

How to prevent it

Generate toolchains.xml from setup-java so it always matches the installed JDK.
Keep the requested toolchain version aligned with what CI installs.
Commit a documented toolchains setup step in the workflow.

Frequently asked questions

What causes Maven toolchains "Cannot find matching toolchain"?

There are 2 common causes: toolchains.xml missing on the runner and no <jdk> entry for the requested version. Maven reads ~/.m2/toolchains.xml.

How do I fix Maven toolchains "Cannot find matching toolchain"?

There are 2 fixes depending on which cause you have: generate toolchains.xml in ci and provide a matching jdk definition. Work through them in order, since the first is the most common.

What does Maven toolchains "Cannot find matching toolchain" actually mean?

The build fails early with Cannot find matching toolchain definitions for the following toolchain types: jdk and the requested version (e.g.

How do I stop Maven toolchains "Cannot find matching toolchain" happening again?

Generate toolchains.xml from setup-java so it always matches the installed JDK. The prevention section lists 3 changes that keep it from recurring.