apache/maven · error · MisconfiguredToolchainException

Non-existing JDK home configuration at " + normal.toAbsolute

Error message

Non-existing JDK home configuration at " + normal.toAbsolutePath()

What it means

After extracting jdkHome from the toolchain configuration, JavaToolchainFactory normalizes the path and checks Files.exists(normal). If the path does not exist on the machine running Maven, MisconfiguredToolchainException('Non-existing JDK home configuration at <absolutePath>') is thrown — the message shows the normalized absolute path that failed the existence check.

Source

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

            } 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);
        return jtc;
    }

    @Override
    public ToolchainPrivate createDefaultToolchain() {
        // not sure it's necessary to provide a default toolchain here.
        // only version can be eventually supplied.

View on GitHub (pinned to e4093d4e12)

Solutions

1. Check the absolute path in the message and correct jdkHome to an existing JDK directory on this machine
2. Use forward slashes on all platforms (C:/Program Files/Eclipse Adoptium/jdk-17) to avoid escaping issues
3. If agents differ, maintain per-machine toolchains.xml instead of sharing one file, or generate it in CI setup from the JAVA_HOME environment variable
4. Verify the directory is a real JDK home (contains bin/java) after fixing the path

Example fix

<!-- before: path does not exist on this machine -->
<jdkHome>C:\Program Files\Java\jdk-17</jdkHome>

<!-- after -->
<jdkHome>/usr/lib/jvm/temurin-17</jdkHome>

import java.nio.file.*;

boolean jdkHomeExists(ToolchainModel model) {
    Xpp3Dom config = (Xpp3Dom) model.getConfiguration();
    Xpp3Dom home = config == null ? null : config.getChild("jdkHome");
    return home != null && Files.isDirectory(Paths.get(home.getValue()).normalize());
}

if (!jdkHomeExists(model)) {
    throw new IllegalStateException("jdkHome in toolchains.xml does not exist on this machine");
}

try {
    toolchainFactory.createToolchain(model, log);
} catch (MisconfiguredToolchainException e) {
    if (e.getMessage().startsWith("Non-existing JDK home")) {
        // message prints the normalized absolute path that failed
        reportEnvError("Install the JDK at the printed path or update toolchains.xml");
    } else {
        throw e;
    }
}

When it happens

Trigger: toolchains.xml with a jdkHome pointing to a directory absent on the current machine: JDK uninstalled/upgraded to a different path, file shared across OSes (Windows path on Linux CI), typos, or unexpanded variables written literally into the XML.

Common situations: CI agents with different JDK install paths than developer machines; JDK version bump changing /usr/lib/jvm/... path; copying a colleague's toolchains.xml; using backslashes or a wrong drive letter on Windows.

Related errors

• Non-existing JDK home configuration at
• Java toolchain without the jdkHome configuration element.
• Directory {} extracted from the -f/--file command-line argum
• Provides token '" + key + "' doesn't have any value configur
• Java toolchain without the jdkHome configuration element.

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