apache/maven · error · FileNotFoundException

The specified project settings file does not exist: {}

Error message

The specified project settings file does not exist: {}

What it means

The -ps / --project-settings option names a project-level settings file. When the option is present, SettingsXmlConfigurationProcessor resolves the path against the working directory and throws FileNotFoundException unless it is an existing regular file. (When the option is absent, Maven instead uses the default .mvn/settings.xml under the detected root directory, without any existence check.)

Source

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

        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(
                    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(

View on GitHub (pinned to e4093d4e12)

Solutions

Check the resolved path in the message and create the file (the conventional location is .mvn/settings.xml at the project root).
Since -ps is explicit, either commit the file or generate it in CI before the mvn call.
If you simply want the default project settings behavior, omit -ps and place the file at .mvn/settings.xml in the root directory.
Run mvn from the directory your relative -ps path is relative to, or use an absolute path.

Example fix

# before
mvn -ps .mvn/settings.xml verify   # file not yet present

# after
mkdir -p .mvn && cp ci/settings.xml .mvn/settings.xml
mvn verify   # default .mvn/settings.xml picked up without -ps

Defensive patterns

Strategy: validation

Validate before calling

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

Try / catch

try {
    mavenCli.doMain(args, ...);
} catch (FileNotFoundException e) {
    if (e.getMessage() != null && e.getMessage().contains("project settings file does not exist")) {
        // create .mvn/settings.xml or drop -ps and rely on the default pickup
    }
    throw e;
}

Prevention

Prefer the conventional .mvn/settings.xml at the project root and omit -ps entirely — Maven picks it up automatically once the root is detected.
Commit a skeleton .mvn/settings.xml if templates expect it, so fresh clones never miss the file.
In monorepos, run mvn from the root or use absolute paths; -ps resolves against cwd, not the module.

When it happens

Trigger: mvn -ps my-settings.xml where the file does not exist or is a directory; relative path evaluated from the wrong cwd. Passing -ps with an empty value resolves to the working directory itself, which fails isFile().

Common situations: Adopting Maven 4 project-level settings and pointing -ps at .mvn/settings.xml before the file is committed/generated. Monorepo pipelines invoking mvn from a subdirectory while the settings file sits at the repo root (relative path resolves against cwd, not the project root).

Related errors

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