{"record":{"id":"5f263efce6f77988","repo":"apache/maven","slug":"the-specified-user-toolchains-file-does-not-exist","errorCode":null,"errorMessage":"The specified user toolchains file does not exist: {}","messagePattern":"The specified user toolchains file does not exist: (.+?)","errorType":"exception","errorClass":"FileNotFoundException","httpStatus":null,"severity":"error","filePath":"compat/maven-embedder/src/main/java/org/apache/maven/cli/MavenCli.java","lineNumber":1241,"sourceCode":"                if (!hint.equals(SettingsXmlConfigurationProcessor.HINT)) {\n                    ConfigurationProcessor configurationProcessor = entry.getValue();\n                    sb.append(String.format(\n                            \"%s%n\", configurationProcessor.getClass().getName()));\n                }\n            }\n            throw new Exception(sb.toString());\n        }\n    }\n\n    void toolchains(CliRequest cliRequest) throws Exception {\n        File userToolchainsFile = null;\n\n        if (cliRequest.commandLine.hasOption(CLIManager.ALTERNATE_USER_TOOLCHAINS)) {\n            userToolchainsFile = new File(cliRequest.commandLine.getOptionValue(CLIManager.ALTERNATE_USER_TOOLCHAINS));\n            userToolchainsFile = ResolveFile.resolveFile(userToolchainsFile, cliRequest.workingDirectory);\n\n            if (!userToolchainsFile.isFile()) {\n                throw new FileNotFoundException(\n                        \"The specified user toolchains file does not exist: \" + userToolchainsFile);\n            }\n        } else {\n            String userToolchainsFileStr = cliRequest.getUserProperties().getProperty(Constants.MAVEN_USER_TOOLCHAINS);\n            if (userToolchainsFileStr != null) {\n                userToolchainsFile = new File(userToolchainsFileStr);\n            }\n        }\n\n        File installationToolchainsFile = null;\n\n        if (cliRequest.commandLine.hasOption(CLIManager.ALTERNATE_INSTALLATION_TOOLCHAINS)) {\n            installationToolchainsFile =\n                    new File(cliRequest.commandLine.getOptionValue(CLIManager.ALTERNATE_INSTALLATION_TOOLCHAINS));\n            installationToolchainsFile =\n                    ResolveFile.resolveFile(installationToolchainsFile, cliRequest.workingDirectory);\n\n            if (!installationToolchainsFile.isFile()) {","sourceCodeStart":1223,"sourceCodeEnd":1259,"githubUrl":"https://github.com/apache/maven/blob/e4093d4e120eac99d6bdce5ba67cace2f3085c97/compat/maven-embedder/src/main/java/org/apache/maven/cli/MavenCli.java#L1223-L1259","documentation":"The -t / --toolchains option points Maven at a user toolchains file. MavenCli.toolchains() resolves the given path via ResolveFile.resolveFile() against the current working directory (making absolute paths out of relative ones) and requires the result to be an existing regular file. If File.isFile() is false it throws FileNotFoundException with the resolved path embedded, before any build starts.","triggerScenarios":"mvn -t toolchains.xml when toolchains.xml is absent from the working directory. Relative paths that resolve against a different cwd (CI steps that cd between checkout and build). Passing a directory, a symlink to a missing target, or a path with a typo. Values injected via wrapper scripts (-t ${TOOLCHAINS_FILE} with the variable empty or wrong).","commonSituations":"CI pipelines that generate the toolchains file in one stage but run mvn -t in another stage/directory where the file was not carried over. Developers switching branches where the file is gitignored locally. Jobs moved between agents with different home layouts while using ~/.m2/toolchains.xml-style relative references.","solutions":["Check the path printed in the message — it is already resolved against the working directory, so verify with ls <printed-path>.","Use an absolute path (or ${session.rootDirectory}/... style anchoring) instead of a relative one when the build may start from a different cwd.","In CI, make sure the toolchains file is created/downloaded before the mvn -t step and persists into that step's workspace.","If you do not need a toolchains file, drop the -t option entirely and rely on the default ~/.m2/toolchains.xml."],"exampleFix":"# before (relative path, wrong cwd)\nmvn -t toolchains/jdk.xml package\n\n# after (absolute path)\nmvn -t \"$PWD/toolchains/jdk.xml\" package","handlingStrategy":"validation","validationCode":"// Java launcher, before doMain\nString tcPath = argAfter(args, \"-t\", \"--toolchains\");\nif (tcPath != null) {\n    Path p = Path.of(workingDir).resolve(tcPath).normalize();\n    if (!Files.isRegularFile(p)) {\n        throw new FileNotFoundException(\"Toolchains file missing, refusing to start mvn: \" + p);\n    }\n}","typeGuard":null,"tryCatchPattern":"try {\n    mavenCli.doMain(args, ...);\n} catch (FileNotFoundException e) {\n    if (e.getMessage() != null && e.getMessage().contains(\"toolchains file does not exist\")) {\n        // report resolved path + cwd, regenerate or fix -t value\n    }\n    throw e;\n}","preventionTips":["Always pass absolute paths for -t in scripts; relative paths resolve against the JVM's cwd, not the project root.","In CI, assert the toolchains file exists in the same step that runs mvn (test -f && mvn -t ...).","Generate the toolchains file idempotently right before the build rather than assuming a prior stage left it behind."],"tags":["maven","cli","toolchains","file-not-found","configuration","path-resolution"],"backgroundTag":"config-file-not-found","analyzedSha":"e4093d4e120eac99d6bdce5ba67cace2f3085c97","analyzedAt":"2026-08-21T22:58:24.034Z","schemaVersion":2},"datasetVersion":"2026-08-21T23:17:16.201Z"}