{"record":{"id":"ab73b4ad345d0adf","repo":"apache/maven","slug":"the-specified-project-settings-file-does-not-exist","errorCode":null,"errorMessage":"The specified project settings file does not exist: {}","messagePattern":"The specified project settings file does not exist: (.+?)","errorType":"exception","errorClass":"FileNotFoundException","httpStatus":null,"severity":"error","filePath":"compat/maven-embedder/src/main/java/org/apache/maven/cli/configuration/SettingsXmlConfigurationProcessor.java","lineNumber":111,"sourceCode":"        if (commandLine.hasOption(CLIManager.ALTERNATE_USER_SETTINGS)) {\n            userSettingsFile = new File(commandLine.getOptionValue(CLIManager.ALTERNATE_USER_SETTINGS));\n            userSettingsFile = resolveFile(userSettingsFile, workingDirectory);\n\n            if (!userSettingsFile.isFile()) {\n                throw new FileNotFoundException(\"The specified user settings file does not exist: \" + userSettingsFile);\n            }\n        } else {\n            userSettingsFile = DEFAULT_USER_SETTINGS_FILE;\n        }\n\n        File projectSettingsFile;\n\n        if (commandLine.hasOption(CLIManager.ALTERNATE_PROJECT_SETTINGS)) {\n            projectSettingsFile = new File(commandLine.getOptionValue(CLIManager.ALTERNATE_PROJECT_SETTINGS));\n            projectSettingsFile = resolveFile(projectSettingsFile, workingDirectory);\n\n            if (!projectSettingsFile.isFile()) {\n                throw new FileNotFoundException(\n                        \"The specified project settings file does not exist: \" + projectSettingsFile);\n            }\n        } else if (cliRequest.getRootDirectory() != null) {\n            projectSettingsFile = DEFAULT_PROJECT_SETTINGS_FILE;\n            projectSettingsFile = resolveFile(\n                    projectSettingsFile, cliRequest.getRootDirectory().toString());\n        } else {\n            projectSettingsFile = null;\n        }\n\n        File installationSettingsFile;\n\n        if (commandLine.hasOption(CLIManager.ALTERNATE_INSTALLATION_SETTINGS)) {\n            installationSettingsFile = new File(commandLine.getOptionValue(CLIManager.ALTERNATE_INSTALLATION_SETTINGS));\n            installationSettingsFile = resolveFile(installationSettingsFile, workingDirectory);\n\n            if (!installationSettingsFile.isFile()) {\n                throw new FileNotFoundException(","sourceCodeStart":93,"sourceCodeEnd":129,"githubUrl":"https://github.com/apache/maven/blob/e4093d4e120eac99d6bdce5ba67cace2f3085c97/compat/maven-embedder/src/main/java/org/apache/maven/cli/configuration/SettingsXmlConfigurationProcessor.java#L93-L129","documentation":"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.)","triggerScenarios":"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().","commonSituations":"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).","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."],"exampleFix":"# before\nmvn -ps .mvn/settings.xml verify   # file not yet present\n\n# after\nmkdir -p .mvn && cp ci/settings.xml .mvn/settings.xml\nmvn verify   # default .mvn/settings.xml picked up without -ps","handlingStrategy":"validation","validationCode":"String s = argAfter(args, \"-ps\", \"--project-settings\");\nif (s != null && !Files.isRegularFile(Path.of(workingDir).resolve(s).normalize())) {\n    throw new FileNotFoundException(\"Project settings file missing, aborting before mvn: \" + s);\n}","typeGuard":null,"tryCatchPattern":"try {\n    mavenCli.doMain(args, ...);\n} catch (FileNotFoundException e) {\n    if (e.getMessage() != null && e.getMessage().contains(\"project settings file does not exist\")) {\n        // create .mvn/settings.xml or drop -ps and rely on the default pickup\n    }\n    throw e;\n}","preventionTips":["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."],"tags":["maven","cli","settings","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"}