Maven Toolchains "Cannot find matching toolchain" - Fix in CI
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.
[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} ]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.
- 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.
<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.