{"record":{"id":"d9c713d4429859d9","repo":"apache/maven","slug":"the-specified-user-settings-file-does-not-exist","errorCode":null,"errorMessage":"The specified user settings file does not exist: {}","messagePattern":"The specified user 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":98,"sourceCode":"    @Inject\n    public SettingsXmlConfigurationProcessor(SettingsBuilder settingsBuilder, SettingsDecrypter settingsDecrypter) {\n        this.settingsBuilder = settingsBuilder;\n    }\n\n    @Override\n    public void process(CliRequest cliRequest) throws Exception {\n        CommandLine commandLine = cliRequest.getCommandLine();\n        String workingDirectory = cliRequest.getWorkingDirectory();\n        MavenExecutionRequest request = cliRequest.getRequest();\n\n        File userSettingsFile;\n\n        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(","sourceCodeStart":80,"sourceCodeEnd":116,"githubUrl":"https://github.com/apache/maven/blob/e4093d4e120eac99d6bdce5ba67cace2f3085c97/compat/maven-embedder/src/main/java/org/apache/maven/cli/configuration/SettingsXmlConfigurationProcessor.java#L80-L116","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"# before\ncd project && mvn -s ../settings.xml deploy   # ../settings.xml missing\n\n# after\nls -la \"$SETTINGS_PATH\" && mvn -s \"$SETTINGS_PATH\" deploy","handlingStrategy":"validation","validationCode":"String s = argAfter(args, \"-s\", \"--settings\");\nif (s != null && !Files.isRegularFile(Path.of(workingDir).resolve(s).normalize())) {\n    throw new FileNotFoundException(\"User 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(\"user settings file does not exist\")) {\n        // regenerate credentials settings in this step, then retry once\n    }\n    throw e;\n}","preventionTips":["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."],"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"}