{"record":{"id":"6a53a687279cdd57","repo":"apache/maven","slug":"unrecognized-maven-config-file-entries","errorCode":null,"errorMessage":"Unrecognized maven.config file entries: {}","messagePattern":"Unrecognized maven\\.config file entries: (.+?)","errorType":"validation","errorClass":"ParseException","httpStatus":null,"severity":"error","filePath":"compat/maven-embedder/src/main/java/org/apache/maven/cli/MavenCli.java","lineNumber":428,"sourceCode":"        // the logger is null and construct this so we can use an SLF4J logger everywhere.\n        //\n        slf4jLogger = new Slf4jStdoutLogger();\n\n        cliManager = new CLIManager();\n\n        CommandLine mavenConfig = null;\n        try {\n            File configFile = new File(cliRequest.multiModuleProjectDirectory, MVN_MAVEN_CONFIG);\n\n            if (configFile.isFile()) {\n                try (Stream<String> lines = Files.lines(configFile.toPath(), StandardCharsets.UTF_8)) {\n                    String[] args = lines.filter(arg -> !arg.isEmpty() && !arg.startsWith(\"#\"))\n                            .toArray(String[]::new);\n                    mavenConfig = cliManager.parse(args);\n                    List<?> unrecognized = mavenConfig.getArgList();\n                    if (!unrecognized.isEmpty()) {\n                        // This file can only contain options, not args (goals or phases)\n                        throw new ParseException(\"Unrecognized maven.config file entries: \" + unrecognized);\n                    }\n                }\n            }\n        } catch (ParseException e) {\n            System.err.println(\"Unable to parse maven.config file options: \" + e.getMessage());\n            cliManager.displayHelp(System.out);\n            throw e;\n        }\n\n        try {\n            CommandLine mavenCli = cliManager.parse(cliRequest.args);\n            if (mavenConfig == null) {\n                cliRequest.commandLine = mavenCli;\n            } else {\n                cliRequest.commandLine = cliMerge(mavenConfig, mavenCli);\n            }\n        } catch (ParseException e) {\n            System.err.println(\"Unable to parse command line options: \" + e.getMessage());","sourceCodeStart":410,"sourceCodeEnd":446,"githubUrl":"https://github.com/apache/maven/blob/e4093d4e120eac99d6bdce5ba67cace2f3085c97/compat/maven-embedder/src/main/java/org/apache/maven/cli/MavenCli.java#L410-L446","documentation":"MavenCli.cli() parses .mvn/maven.config early in startup. That file may contain only options (like -D..., -s, -T), never goals or phases; any unrecognized non-option token ends up in the parsed CommandLine's argument list, and ParseException('Unrecognized maven.config file entries: <entries>') is thrown. It is then reported to the user as 'Unable to parse maven.config file options: ...', the CLI help is displayed, and startup aborts.","triggerScenarios":"A .mvn/maven.config containing goals/phases (e.g. a line 'clean install') or any bare token that is not an option; also lines formatted as 'option value' in the pre-3.9.0 single-token-per-line style that produce stray unrecognized arguments under newer parsers.","commonSituations":"Teams trying to set default goals via maven.config (not supported — that belongs to the shell alias or CI command); migrating a Maven 3.3–3.8 style maven.config to 3.9+ where each line must be a single self-contained argument; leftover junk lines or comments not prefixed with '#'.","solutions":["Edit .mvn/maven.config in the project root and remove the quoted entries from the message — goals and phases are not allowed there","Keep one option per line, with values joined to their flag (-Dkey=value, -T=4, or -s settings.xml style per your Maven version's format)","Prefix informational lines with # so they are filtered out as comments","Put default goals/phases in the CI invocation or a shell alias instead of maven.config"],"exampleFix":"# .mvn/maven.config — before\n-DskipTests=false\nclean install\n\n# .mvn/maven.config — after\n-DskipTests=false","handlingStrategy":"validation","validationCode":"import java.nio.file.*;\nimport java.util.*;\n\n// lint .mvn/maven.config: every line must be blank, a comment, or start with '-'\nvoid lintMavenConfig(Path projectRoot) throws IOException {\n    Path cfg = projectRoot.resolve(\".mvn/maven.config\");\n    if (Files.isRegularFile(cfg)) {\n        try (var lines = Files.lines(cfg)) {\n            List<String> bad = lines.map(String::trim)\n                    .filter(l -> !l.isEmpty() && !l.startsWith(\"#\") && !l.startsWith(\"-\"))\n                    .toList();\n            if (!bad.isEmpty()) {\n                throw new IllegalStateException(\n                    \"maven.config may contain options only; offending lines: \" + bad);\n            }\n        }\n    }\n}","typeGuard":null,"tryCatchPattern":"catch (ExitException e) { // after cliManager.parse inside MavenCli.cli(); catch ParseException when embedding\n    if (e instanceof ParseException pe\n            && pe.getMessage() != null && pe.getMessage().startsWith(\"Unrecognized maven.config file entries\")) {\n        // message lists the offending entries; strip them from .mvn/maven.config and rerun\n        fixMavenConfigAndRetry(projectRoot);\n    }\n}","preventionTips":["Keep .mvn/maven.config options-only: one option per line, values attached to their flag","Put default goals in CI pipelines or shell aliases — maven.config rejects goals and phases by design","Add a config lint step (or maven-enforcer rule in a parent POM) so invalid maven.config entries fail with a clear message in review, not at build startup"],"tags":["maven","cli","config-file","maven-config","arguments"],"backgroundTag":"invalid-config-entries","analyzedSha":"e4093d4e120eac99d6bdce5ba67cace2f3085c97","analyzedAt":"2026-08-21T22:58:24.034Z","schemaVersion":2},"datasetVersion":"2026-08-21T23:17:16.201Z"}