apache/maven · error · MisconfiguredToolchainException

Cannot read toolchains file at " + userToolchainsFile.getAbs

Error message

Cannot read toolchains file at " + userToolchainsFile.getAbsolutePath()

What it means

DefaultToolchainsBuilder.build(File) reads ~/.m2/toolchains.xml with a StAX reader (MavenToolchainsStaxReader) inside a try-with-resources; any IOException or XML parsing exception from reading or parsing is wrapped in MisconfiguredToolchainException('Cannot read toolchains file at <absolutePath>'). The file was found (isFile() was true), so this is a read/parse failure, not a missing file.

Source

Thrown at compat/maven-compat/src/main/java/org/apache/maven/toolchain/DefaultToolchainsBuilder.java:50

/**
 * @deprecated instead use {@link org.apache.maven.toolchain.building.DefaultToolchainsBuilder}
 */
@Deprecated
@Named("default")
@Singleton
public class DefaultToolchainsBuilder implements ToolchainsBuilder {
    private final Logger logger = LoggerFactory.getLogger(getClass());

    @Override
    public PersistedToolchains build(File userToolchainsFile) throws MisconfiguredToolchainException {
        PersistedToolchains toolchains = null;

        if (userToolchainsFile != null && userToolchainsFile.isFile()) {
            try (InputStream in = Files.newInputStream(userToolchainsFile.toPath())) {
                toolchains = new PersistedToolchains(new MavenToolchainsStaxReader().read(in));
            } catch (Exception e) {
                throw new MisconfiguredToolchainException(
                        "Cannot read toolchains file at " + userToolchainsFile.getAbsolutePath(), e);
            }

        } else if (userToolchainsFile != null) {
            logger.debug("Toolchains configuration was not found at {}", userToolchainsFile);
        }

        return toolchains;
    }
}

View on GitHub (pinned to e4093d4e12)

Solutions

Open the path shown in the message and validate the XML (well-formedness first, then element names) with an editor or xmllint
Compare against the documented toolchains.xml skeleton: <toolchains><toolchain><type>jdk</type>...</toolchain></toolchains>
Fix file permissions/locks if reading fails at the OS level, then rerun mvn --toolchains or a normal build
If the file is beyond repair, delete it and regenerate from a minimal known-good template

Example fix

<!-- before: mismatched tags -->
<toolchains>
  <toolchain>
    <type>jdk</type>
    <provides>
      <version>17</version>
    </provide>
  </toolchain>
</toolchains>

<!-- after -->
<toolchains>
  <toolchain>
    <type>jdk</type>
    <provides>
      <version>17</version>
    </provides>
  </toolchain>
</toolchains>

Defensive patterns

Strategy: validation

Validate before calling

import java.nio.file.*;
import javax.xml.XMLConstants;
import javax.xml.parsers.*;

void assertToolchainsXmlParses(Path file) throws IOException {
    if (Files.isRegularFile(file)) {
        try {
            DocumentBuilderFactory dbf = DocumentBuilderFactory.newInstance();
            dbf.setFeature("http://apache.org/xml/features/disallow-doctype-decl", true);
            dbf.newDocumentBuilder().parse(Files.newInputStream(file)); // well-formedness check
        } catch (Exception e) {
            throw new IllegalStateException("toolchains.xml is not well-formed XML: " + e.getMessage(), e);
        }
    }
}

Try / catch

try {
    PersistedToolchains toolchains = toolchainsBuilder.build(toolchainsFile);
} catch (MisconfiguredToolchainException e) {
    if (e.getMessage().startsWith("Cannot read toolchains file")) {
        // show the user the exact path and the parse cause for a targeted fix
        failWithHint("Fix or delete " + toolchainsFile.getAbsolutePath(), e.getCause());
    } else {
        throw e;
    }
}

Prevention

Validate toolchains.xml in editor tooling with the published XML schema or a known-good template
Generate the file from a template in provisioning scripts instead of hand-editing on each machine
Keep a minimal working toolchains.xml checked into team docs so recovery is copy-paste

When it happens

Trigger: toolchains.xml exists but is malformed: mismatched or unclosed tags, wrong root element (<toolchains> expected), invalid XML characters or a BOM confusing the parser, or an OS-level read failure (permissions, file locked by another process).

Common situations: Hand-edited toolchains.xml with a typo; file generated by a script that truncated it; encoding issues after editing on Windows; deployment tooling writing the file with wrong permissions.

Related errors

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