{"record":{"id":"389b03edf16138b6","repo":"apache/maven","slug":"cannot-read-toolchains-file-at-usertoolchainsf","errorCode":null,"errorMessage":"Cannot read toolchains file at \" + userToolchainsFile.getAbsolutePath()","messagePattern":"Cannot read toolchains file at \" \\+ userToolchainsFile\\.getAbsolutePath\\(\\)","errorType":"exception","errorClass":"MisconfiguredToolchainException","httpStatus":null,"severity":"error","filePath":"compat/maven-compat/src/main/java/org/apache/maven/toolchain/DefaultToolchainsBuilder.java","lineNumber":50,"sourceCode":"\n/**\n * @deprecated instead use {@link org.apache.maven.toolchain.building.DefaultToolchainsBuilder}\n */\n@Deprecated\n@Named(\"default\")\n@Singleton\npublic class DefaultToolchainsBuilder implements ToolchainsBuilder {\n    private final Logger logger = LoggerFactory.getLogger(getClass());\n\n    @Override\n    public PersistedToolchains build(File userToolchainsFile) throws MisconfiguredToolchainException {\n        PersistedToolchains toolchains = null;\n\n        if (userToolchainsFile != null && userToolchainsFile.isFile()) {\n            try (InputStream in = Files.newInputStream(userToolchainsFile.toPath())) {\n                toolchains = new PersistedToolchains(new MavenToolchainsStaxReader().read(in));\n            } catch (Exception e) {\n                throw new MisconfiguredToolchainException(\n                        \"Cannot read toolchains file at \" + userToolchainsFile.getAbsolutePath(), e);\n            }\n\n        } else if (userToolchainsFile != null) {\n            logger.debug(\"Toolchains configuration was not found at {}\", userToolchainsFile);\n        }\n\n        return toolchains;\n    }\n}\n","sourceCodeStart":32,"sourceCodeEnd":61,"githubUrl":"https://github.com/apache/maven/blob/e4093d4e120eac99d6bdce5ba67cace2f3085c97/compat/maven-compat/src/main/java/org/apache/maven/toolchain/DefaultToolchainsBuilder.java#L32-L61","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","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"],"exampleFix":"<!-- before: mismatched tags -->\n<toolchains>\n  <toolchain>\n    <type>jdk</type>\n    <provides>\n      <version>17</version>\n    </provide>\n  </toolchain>\n</toolchains>\n\n<!-- after -->\n<toolchains>\n  <toolchain>\n    <type>jdk</type>\n    <provides>\n      <version>17</version>\n    </provides>\n  </toolchain>\n</toolchains>","handlingStrategy":"validation","validationCode":"import java.nio.file.*;\nimport javax.xml.XMLConstants;\nimport javax.xml.parsers.*;\n\nvoid assertToolchainsXmlParses(Path file) throws IOException {\n    if (Files.isRegularFile(file)) {\n        try {\n            DocumentBuilderFactory dbf = DocumentBuilderFactory.newInstance();\n            dbf.setFeature(\"http://apache.org/xml/features/disallow-doctype-decl\", true);\n            dbf.newDocumentBuilder().parse(Files.newInputStream(file)); // well-formedness check\n        } catch (Exception e) {\n            throw new IllegalStateException(\"toolchains.xml is not well-formed XML: \" + e.getMessage(), e);\n        }\n    }\n}","typeGuard":null,"tryCatchPattern":"try {\n    PersistedToolchains toolchains = toolchainsBuilder.build(toolchainsFile);\n} catch (MisconfiguredToolchainException e) {\n    if (e.getMessage().startsWith(\"Cannot read toolchains file\")) {\n        // show the user the exact path and the parse cause for a targeted fix\n        failWithHint(\"Fix or delete \" + toolchainsFile.getAbsolutePath(), e.getCause());\n    } else {\n        throw e;\n    }\n}","preventionTips":["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"],"tags":["maven","toolchains","xml","configuration","parse-error"],"backgroundTag":"config-file-parse-error","analyzedSha":"e4093d4e120eac99d6bdce5ba67cace2f3085c97","analyzedAt":"2026-08-21T22:58:24.034Z","schemaVersion":2},"datasetVersion":"2026-08-21T23:17:16.201Z"}