apache/maven · error · FileNotFoundException

The specified installation settings file does not exist: {}

Error message

The specified installation settings file does not exist: {}

What it means

The -is / --install-settings option names the installation-level settings file. SettingsXmlConfigurationProcessor checks it first (before -gs): the path is resolved against the working directory and must be an existing regular file, otherwise FileNotFoundException is thrown. Note that when -is is present, the -gs branch is never reached, so an error mentioning 'installation settings file' can come from either option.

Source

Thrown at compat/maven-embedder/src/main/java/org/apache/maven/cli/configuration/SettingsXmlConfigurationProcessor.java:129

                throw new FileNotFoundException(
                        "The specified project settings file does not exist: " + projectSettingsFile);
            }
        } else if (cliRequest.getRootDirectory() != null) {
            projectSettingsFile = DEFAULT_PROJECT_SETTINGS_FILE;
            projectSettingsFile = resolveFile(
                    projectSettingsFile, cliRequest.getRootDirectory().toString());
        } else {
            projectSettingsFile = null;
        }

        File installationSettingsFile;

        if (commandLine.hasOption(CLIManager.ALTERNATE_INSTALLATION_SETTINGS)) {
            installationSettingsFile = new File(commandLine.getOptionValue(CLIManager.ALTERNATE_INSTALLATION_SETTINGS));
            installationSettingsFile = resolveFile(installationSettingsFile, workingDirectory);

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

            if (!installationSettingsFile.isFile()) {
                throw new FileNotFoundException(
                        "The specified installation settings file does not exist: " + installationSettingsFile);
            }
        } else {
            installationSettingsFile = DEFAULT_INSTALLATION_SETTINGS_FILE;
        }

        request.setInstallationSettingsFile(installationSettingsFile);
        request.setProjectSettingsFile(projectSettingsFile);
        request.setUserSettingsFile(userSettingsFile);

View on GitHub (pinned to e4093d4e12)

Solutions

Verify the resolved path from the message exists (ls) and create/restore the file.
Bake or mount the settings file into the environment at a stable absolute path and point -is at it.
If you intended the classic global settings option, use -gs /path or the default installation location instead — but note both must exist.
If you do not need an installation-level file, drop the option and rely on user (-s / ~/.m2/settings.xml) or project (.mvn/settings.xml) settings.

Example fix

# before
mvn -is /opt/maven/conf/settings.xml deploy   # path absent in slim image

# after
copy ci/install-settings.xml /opt/maven/conf/settings.xml  (Dockerfile)
mvn -is /opt/maven/conf/settings.xml deploy

Defensive patterns

Strategy: validation

Validate before calling

String s = argAfter(args, "-is", "--install-settings");
if (s != null && !Files.isRegularFile(Path.of(workingDir).resolve(s).normalize())) {
    throw new FileNotFoundException("Installation settings file missing, aborting before mvn: " + s);
}

Try / catch

try {
    mavenCli.doMain(args, ...);
} catch (FileNotFoundException e) {
    if (e.getMessage() != null && e.getMessage().contains("installation settings file does not exist")) {
        // check whether -is or -gs supplied the bad path, fix provisioning, retry
    }
    throw e;
}

Prevention

Bake installation-level settings into the Maven distribution/image at a fixed absolute path so -is always resolves.
Note -is takes precedence over -gs; when both are passed, the -is file is the one checked first.
Add image-level smoke tests (mvn -is <path> -v) to CI for custom distributions.

When it happens

Trigger: mvn -is /opt/maven/conf/settings.xml (or the long form) where the path does not exist on the machine/container. Relative -is paths evaluated from a different working directory. Passing a directory or dangling symlink.

Common situations: Custom Maven distributions or Docker images where the conf/settings.xml was moved or removed during image slimming. Pipelines migrating from -gs to Maven 4's -is spelling without provisioning the file at the new expected location. Agent fleets with heterogeneous install paths.

Related errors

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