apache/maven · error · ToolchainsBuilderException

Error building toolchains

Error message

Error building toolchains

What it means

Thrown by DefaultToolchainsBuilder.build when merging the installation-level and user-level toolchains.xml produces error-severity problems, for example parse failures in either file. The exception carries the ProblemCollector of BuilderProblem entries; iterating them yields the failing file and location.

Source

Thrown at impl/maven-impl/src/main/java/org/apache/maven/impl/DefaultToolchainsBuilder.java:78

    public DefaultToolchainsBuilder(Interpolator interpolator, ToolchainsXmlFactory toolchainsXmlFactory) {
        this.interpolator = interpolator;
        this.toolchainsXmlFactory = toolchainsXmlFactory;
    }

    @Override
    public ToolchainsBuilderResult build(ToolchainsBuilderRequest request) throws ToolchainsBuilderException {
        ProblemCollector<BuilderProblem> problems = ProblemCollector.create(request.getSession());

        Source installationSource = request.getInstallationToolchainsSource().orElse(null);
        PersistedToolchains installation = readToolchains(installationSource, request, problems);

        Source userSource = request.getUserToolchainsSource().orElse(null);
        PersistedToolchains user = readToolchains(userSource, request, problems);

        PersistedToolchains effective = toolchainsMerger.merge(user, installation, false, null);

        if (problems.hasErrorProblems()) {
            throw new ToolchainsBuilderException("Error building toolchains", problems);
        }

        return new DefaultToolchainsBuilderResult(request, effective, problems);
    }

    private PersistedToolchains readToolchains(
            Source toolchainsSource, ToolchainsBuilderRequest request, ProblemCollector<BuilderProblem> problems) {
        if (toolchainsSource == null) {
            return PersistedToolchains.newInstance();
        }

        PersistedToolchains toolchains;

        try {
            try {
                InputStream is = toolchainsSource.openStream();
                if (is == null) {
                    return PersistedToolchains.newInstance();

View on GitHub (pinned to e4093d4e12)

Solutions

1. Catch ToolchainsBuilderException and iterate the attached problem collector for file and line details
2. Fix the reported XML in the named toolchains file
3. Temporarily rename the toolchains files to confirm which source produces the error

Example fix

// before
ToolchainsBuilderResult result = toolchainsBuilder.build(request);

// after
try {
    ToolchainsBuilderResult result = toolchainsBuilder.build(request);
} catch (ToolchainsBuilderException e) {
    e.getProblemCollector().getProblems()
        .forEach(p -> log.error("{}: {}", p.getLocation(), p.getMessage()));
}

try {
    ToolchainsBuilderResult result = toolchainsBuilder.build(request);
} catch (ToolchainsBuilderException e) {
    e.getProblemCollector().getProblems()
        .forEach(p -> log.error("{}: {}", p.getLocation(), p.getMessage()));
    // fall back to no toolchains rather than abort the build, if acceptable
}

When it happens

Trigger: Malformed toolchains.xml in ~/.m2/toolchains.xml or in the installation-level file; toolchains sources that exist but cannot be read or parsed.

Common situations: Hand-edited toolchains.xml with XML errors; CI-managed toolchains files corrupted during provisioning; merge of user and installation files surfacing conflicting definitions.

Related errors

• Only fully-qualified sets allowed in multiple set scenario:
• Single version must be surrounded by []: {}
• Cannot read toolchains file at " + userToolchainsFile.getAbs
• 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/83cd5aa9e133edf8. Report an issue: GitHub.