What causes "The specified user settings file does not exist: {}" in apache/maven?

Verify the resolved path from the message with ls; create or fix the file location.

apache/maven · error · FileNotFoundException

The specified user settings file does not exist: {}

Error message

The specified user settings file does not exist: {}

What it means

The -s / --settings option names the user settings file. SettingsXmlConfigurationProcessor.process() resolves the path against the working directory and throws FileNotFoundException when the resolved File fails File.isFile() — missing, a directory, or an unreadable dangling symlink. This runs during CLI configuration, before the project is built.

Source

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

    @Inject
    public SettingsXmlConfigurationProcessor(SettingsBuilder settingsBuilder, SettingsDecrypter settingsDecrypter) {
        this.settingsBuilder = settingsBuilder;
    }

    @Override
    public void process(CliRequest cliRequest) throws Exception {
        CommandLine commandLine = cliRequest.getCommandLine();
        String workingDirectory = cliRequest.getWorkingDirectory();
        MavenExecutionRequest request = cliRequest.getRequest();

        File userSettingsFile;

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

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

        File projectSettingsFile;

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

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

View on GitHub (pinned to e4093d4e12)

Solutions

Verify the resolved path from the message with ls; create or fix the file location.
Use an absolute path, or ensure the build command runs from the directory the relative path is anchored to.
In CI, write/download the settings file in the same job step (or before) the mvn -s invocation.
If the file is optional, drop -s and rely on the default ~/.m2/settings.xml.

Example fix

# before
cd project && mvn -s ../settings.xml deploy   # ../settings.xml missing

# after
ls -la "$SETTINGS_PATH" && mvn -s "$SETTINGS_PATH" deploy

Defensive patterns

Strategy: validation

Validate before calling

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

Try / catch

try {
    mavenCli.doMain(args, ...);
} catch (FileNotFoundException e) {
    if (e.getMessage() != null && e.getMessage().contains("user settings file does not exist")) {
        // regenerate credentials settings in this step, then retry once
    }
    throw e;
}

Prevention

Generate settings.xml in the same CI step that runs mvn (write to a temp path, then -s that path).
Use absolute paths for -s; relative ones resolve against the JVM working directory.
Wrap generation scripts with set -euo pipefail so a failed credential fetch aborts before mvn runs with a stale/missing file.

When it happens

Trigger: mvn -s settings-custom.xml with the file absent from the cwd; a relative path resolved from a different working directory (CI steps, IDE runners, scripted cd); passing a directory path; a wrapper script interpolating -s ${SETTINGS} where the variable is empty or wrong.

Common situations: CI jobs generating settings.xml (with credentials) per pipeline but running mvn before the file is written, or in a different workspace path. Developers referencing a colleague's absolute path. Docker builds copying settings.xml to a different location than the -s argument uses.

Related errors

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