apache/maven · error · MisconfiguredToolchainException

Java toolchain without the jdkHome configuration element.

Error message

Java toolchain without the jdkHome configuration element.

What it means

JavaToolchainFactory requires every jdk toolchain to carry a <configuration> block containing a <jdkHome> child (JavaToolchainImpl.KEY_JAVAHOME). If the configuration DOM is absent or has no jdkHome child, MisconfiguredToolchainException('Java toolchain without the jdkHome configuration element.') is thrown before the path is even inspected.

Source

Thrown at compat/maven-compat/src/main/java/org/apache/maven/toolchain/java/JavaToolchainFactory.java:88

                throw new MisconfiguredToolchainException(
                        "Provides token '" + key + "' doesn't have any value configured.");
            }

            RequirementMatcher matcher;
            if ("version".equals(key)) {
                matcher = RequirementMatcherFactory.createVersionMatcher(value);
            } else {
                matcher = RequirementMatcherFactory.createExactMatcher(value);
            }

            jtc.addProvideToken(key, matcher);
        }

        // populate the configuration section
        Xpp3Dom dom = (Xpp3Dom) model.getConfiguration();
        Xpp3Dom javahome = dom != null ? dom.getChild(JavaToolchainImpl.KEY_JAVAHOME) : null;
        if (javahome == null) {
            throw new MisconfiguredToolchainException(
                    "Java toolchain without the " + JavaToolchainImpl.KEY_JAVAHOME + " configuration element.");
        }
        Path normal = Paths.get(javahome.getValue()).normalize();
        if (Files.exists(normal)) {
            jtc.setJavaHome(Paths.get(javahome.getValue()).normalize().toString());
        } else {
            throw new MisconfiguredToolchainException(
                    "Non-existing JDK home configuration at " + normal.toAbsolutePath());
        }

        ArtifactVersion javaVersion = model.getProvides().entrySet().stream()
                .filter(entry -> "version".equals(entry.getKey()))
                .map(Map.Entry::getValue)
                .map(v -> new DefaultArtifactVersion((String) v))
                .findAny()
                .orElse(null);

        jtc.setJavaVersion(javaVersion);

View on GitHub (pinned to e4093d4e12)

Solutions

Add <configuration><jdkHome>/path/to/jdk</jdkHome></configuration> inside the jdk toolchain element
Verify jdkHome is a direct child of <configuration>, not of <toolchain> or <provides>
Point jdkHome at a JDK home directory (containing bin/java), then rerun the build using the toolchains plugin

Example fix

<!-- before -->
<toolchain>
  <type>jdk</type>
  <provides>
    <version>17</version>
  </provides>
</toolchain>

<!-- after -->
<toolchain>
  <type>jdk</type>
  <provides>
    <version>17</version>
  </provides>
  <configuration>
    <jdkHome>/usr/lib/jvm/temurin-17</jdkHome>
  </configuration>
</toolchain>

Defensive patterns

Strategy: validation

Validate before calling

import org.apache.maven.toolchain.model.ToolchainModel;
import org.codehaus.plexus.util.xml.Xpp3Dom;

boolean hasJdkHome(ToolchainModel model) {
    Xpp3Dom config = (Xpp3Dom) model.getConfiguration();
    return config != null && config.getChild("jdkHome") != null;
}

if ("jdk".equals(model.getType()) && !hasJdkHome(model)) {
    throw new IllegalStateException("jdk toolchain requires <configuration><jdkHome>...</jdkHome>");
}

Try / catch

try {
    toolchainFactory.createToolchain(model, log);
} catch (MisconfiguredToolchainException e) {
    if (e.getMessage().contains("jdkHome configuration element")) {
        reportToolchainsXmlError("Add <configuration><jdkHome>/path/to/jdk</jdkHome></configuration>");
    } else {
        throw e;
    }
}

Prevention

Use a template toolchains.xml that already contains the configuration block
After editing, run a quick toolchains smoke build (mvn -Dtoolchain=jdk toolchains:toolchain or a project requiring it) to catch config gaps early
Never split provides and configuration across separate files or profiles — the factory reads one model

When it happens

Trigger: A toolchains.xml <toolchain><type>jdk</type> entry that omits <configuration> or whose <configuration> lacks <jdkHome> — e.g. only <provides> was filled in.

Common situations: Minimal hand-written toolchain entries copied from blog posts that skip the configuration section; migration from scripts that only recorded the Java version; XML indentation mistakes nesting jdkHome outside <configuration>.

Related errors

AI-assisted analysis of apache/maven@e4093d4e12 (2026-08-21). Data as JSON: /api/errors/909a8fa8211a2d7c. Report an issue: GitHub.