apache/maven · error · FileNotFoundException

The specified installation toolchains file does not exist: {

Error message

The specified installation toolchains file does not exist: {}

What it means

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.

Source

Thrown at compat/maven-embedder/src/main/java/org/apache/maven/cli/MavenCli.java:1260

                        "The specified user toolchains file does not exist: " + userToolchainsFile);
            }
        } else {
            String userToolchainsFileStr = cliRequest.getUserProperties().getProperty(Constants.MAVEN_USER_TOOLCHAINS);
            if (userToolchainsFileStr != null) {
                userToolchainsFile = new File(userToolchainsFileStr);
            }
        }

        File installationToolchainsFile = null;

        if (cliRequest.commandLine.hasOption(CLIManager.ALTERNATE_INSTALLATION_TOOLCHAINS)) {
            installationToolchainsFile =
                    new File(cliRequest.commandLine.getOptionValue(CLIManager.ALTERNATE_INSTALLATION_TOOLCHAINS));
            installationToolchainsFile =
                    ResolveFile.resolveFile(installationToolchainsFile, cliRequest.workingDirectory);

            if (!installationToolchainsFile.isFile()) {
                throw new FileNotFoundException(
                        "The specified installation toolchains file does not exist: " + installationToolchainsFile);
            }
        } else if (cliRequest.commandLine.hasOption(CLIManager.ALTERNATE_GLOBAL_TOOLCHAINS)) {
            installationToolchainsFile =
                    new File(cliRequest.commandLine.getOptionValue(CLIManager.ALTERNATE_GLOBAL_TOOLCHAINS));
            installationToolchainsFile =
                    ResolveFile.resolveFile(installationToolchainsFile, cliRequest.workingDirectory);

            if (!installationToolchainsFile.isFile()) {
                throw new FileNotFoundException(
                        "The specified installation toolchains file does not exist: " + installationToolchainsFile);
            }
        } else {
            String installationToolchainsFileStr =
                    cliRequest.getUserProperties().getProperty(Constants.MAVEN_INSTALLATION_TOOLCHAINS);
            if (installationToolchainsFileStr != null) {
                installationToolchainsFile = new File(installationToolchainsFileStr);
                installationToolchainsFile =

View on GitHub (pinned to e4093d4e12)

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.

Example fix

# before
mvn -it conf/toolchains.xml verify   # conf/ does not exist in cwd

# after
mvn -it /opt/maven/conf/toolchains.xml verify

Defensive patterns

Strategy: validation

Validate before calling

String p = argAfter(args, "-it", "--install-toolchains");
if (p != null && !Files.isRegularFile(Path.of(workingDir).resolve(p).normalize())) {
    throw new FileNotFoundException("Installation toolchains file missing: " + p);
}

Try / catch

try { mavenCli.doMain(args, ...); } catch (FileNotFoundException e) { /* match 'installation toolchains file does not exist', verify provisioning, re-run */ throw e; }

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

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