{"record":{"id":"b14f004b5693c08d","repo":"apache/maven","slug":"the-specified-installation-toolchains-file-does-no","errorCode":null,"errorMessage":"The specified installation toolchains file does not exist: {}","messagePattern":"The specified installation 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":1260,"sourceCode":"                        \"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()) {\n                throw new FileNotFoundException(\n                        \"The specified installation toolchains file does not exist: \" + installationToolchainsFile);\n            }\n        } else if (cliRequest.commandLine.hasOption(CLIManager.ALTERNATE_GLOBAL_TOOLCHAINS)) {\n            installationToolchainsFile =\n                    new File(cliRequest.commandLine.getOptionValue(CLIManager.ALTERNATE_GLOBAL_TOOLCHAINS));\n            installationToolchainsFile =\n                    ResolveFile.resolveFile(installationToolchainsFile, cliRequest.workingDirectory);\n\n            if (!installationToolchainsFile.isFile()) {\n                throw new FileNotFoundException(\n                        \"The specified installation toolchains file does not exist: \" + installationToolchainsFile);\n            }\n        } else {\n            String installationToolchainsFileStr =\n                    cliRequest.getUserProperties().getProperty(Constants.MAVEN_INSTALLATION_TOOLCHAINS);\n            if (installationToolchainsFileStr != null) {\n                installationToolchainsFile = new File(installationToolchainsFileStr);\n                installationToolchainsFile =","sourceCodeStart":1242,"sourceCodeEnd":1278,"githubUrl":"https://github.com/apache/maven/blob/e4093d4e120eac99d6bdce5ba67cace2f3085c97/compat/maven-embedder/src/main/java/org/apache/maven/cli/MavenCli.java#L1242-L1278","documentation":"The -it / --install-toolchains option (CLIManager.ALTERNATE_INSTALLATION_TOOLCHAINS) selects the installation-level toolchains file. MavenCli.toolchains() resolves the path against the working directory and throws FileNotFoundException when the target is not an existing regular file. Note this check wins over the global (-gt) branch because the if/else tests the installation option first.","triggerScenarios":"mvn -it /path/to/toolchains.xml (or the long form --install-toolchains) where the path does not exist, is a directory, or is a relative path that does not resolve from the current working directory.","commonSituations":"Migrating CI from the deprecated -gt global toolchains to the Maven 4 installation-level -it option and pointing it at a file that was never provisioned on the agent. Absolute paths like /opt/maven/conf/toolchains.xml that differ across build agents. Typos in centrally managed pipeline templates.","solutions":["Verify the exact resolved path from the exception message with ls; fix the typo or create the file.","Use an absolute path to a file you have provisioned (e.g. via CI configuration management) rather than a relative one.","If you meant to point at the global toolchains file, use -gt instead, or omit both and place the file at the default installation location.","Provision the toolchains file in the environment (template it per-agent) before running mvn -it."],"exampleFix":"# before\nmvn -it conf/toolchains.xml verify   # conf/ does not exist in cwd\n\n# after\nmvn -it /opt/maven/conf/toolchains.xml verify","handlingStrategy":"validation","validationCode":"String p = argAfter(args, \"-it\", \"--install-toolchains\");\nif (p != null && !Files.isRegularFile(Path.of(workingDir).resolve(p).normalize())) {\n    throw new FileNotFoundException(\"Installation toolchains file missing: \" + p);\n}","typeGuard":null,"tryCatchPattern":"try { mavenCli.doMain(args, ...); } catch (FileNotFoundException e) { /* match 'installation toolchains file does not exist', verify provisioning, re-run */ throw e; }","preventionTips":["Provision the installation toolchains file with configuration management (image build, ansible) so the -it path is guaranteed on every agent.","Prefer absolute, installation-anchored paths over cwd-relative ones for installation-level config.","Add a preflight check in wrappers: test -f \"$TOOLCHAINS\" || exit with a clear message."],"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"}