{"record":{"id":"f0709762b0e42e5e","repo":"apache/maven","slug":"the-specified-installation-settings-file-does-not","errorCode":null,"errorMessage":"The specified installation settings file does not exist: {}","messagePattern":"The specified installation 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":129,"sourceCode":"                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(\n                        \"The specified installation settings file does not exist: \" + installationSettingsFile);\n            }\n        } else if (commandLine.hasOption(CLIManager.ALTERNATE_GLOBAL_SETTINGS)) {\n            installationSettingsFile = new File(commandLine.getOptionValue(CLIManager.ALTERNATE_GLOBAL_SETTINGS));\n            installationSettingsFile = resolveFile(installationSettingsFile, workingDirectory);\n\n            if (!installationSettingsFile.isFile()) {\n                throw new FileNotFoundException(\n                        \"The specified installation settings file does not exist: \" + installationSettingsFile);\n            }\n        } else {\n            installationSettingsFile = DEFAULT_INSTALLATION_SETTINGS_FILE;\n        }\n\n        request.setInstallationSettingsFile(installationSettingsFile);\n        request.setProjectSettingsFile(projectSettingsFile);\n        request.setUserSettingsFile(userSettingsFile);\n","sourceCodeStart":111,"sourceCodeEnd":147,"githubUrl":"https://github.com/apache/maven/blob/e4093d4e120eac99d6bdce5ba67cace2f3085c97/compat/maven-embedder/src/main/java/org/apache/maven/cli/configuration/SettingsXmlConfigurationProcessor.java#L111-L147","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"# before\nmvn -is /opt/maven/conf/settings.xml deploy   # path absent in slim image\n\n# after\ncopy ci/install-settings.xml /opt/maven/conf/settings.xml  (Dockerfile)\nmvn -is /opt/maven/conf/settings.xml deploy","handlingStrategy":"validation","validationCode":"String s = argAfter(args, \"-is\", \"--install-settings\");\nif (s != null && !Files.isRegularFile(Path.of(workingDir).resolve(s).normalize())) {\n    throw new FileNotFoundException(\"Installation 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(\"installation settings file does not exist\")) {\n        // check whether -is or -gs supplied the bad path, fix provisioning, retry\n    }\n    throw e;\n}","preventionTips":["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."],"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"}