apache/maven · error · ParseException

Unrecognized maven.config file entries: {}

Error message

Unrecognized maven.config file entries: {}

What it means

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.

Source

Thrown at compat/maven-embedder/src/main/java/org/apache/maven/cli/MavenCli.java:428

        // the logger is null and construct this so we can use an SLF4J logger everywhere.
        //
        slf4jLogger = new Slf4jStdoutLogger();

        cliManager = new CLIManager();

        CommandLine mavenConfig = null;
        try {
            File configFile = new File(cliRequest.multiModuleProjectDirectory, MVN_MAVEN_CONFIG);

            if (configFile.isFile()) {
                try (Stream<String> lines = Files.lines(configFile.toPath(), StandardCharsets.UTF_8)) {
                    String[] args = lines.filter(arg -> !arg.isEmpty() && !arg.startsWith("#"))
                            .toArray(String[]::new);
                    mavenConfig = cliManager.parse(args);
                    List<?> unrecognized = mavenConfig.getArgList();
                    if (!unrecognized.isEmpty()) {
                        // This file can only contain options, not args (goals or phases)
                        throw new ParseException("Unrecognized maven.config file entries: " + unrecognized);
                    }
                }
            }
        } catch (ParseException e) {
            System.err.println("Unable to parse maven.config file options: " + e.getMessage());
            cliManager.displayHelp(System.out);
            throw e;
        }

        try {
            CommandLine mavenCli = cliManager.parse(cliRequest.args);
            if (mavenConfig == null) {
                cliRequest.commandLine = mavenCli;
            } else {
                cliRequest.commandLine = cliMerge(mavenConfig, mavenCli);
            }
        } catch (ParseException e) {
            System.err.println("Unable to parse command line options: " + e.getMessage());

View on GitHub (pinned to e4093d4e12)

Solutions

1. Edit .mvn/maven.config in the project root and remove the quoted entries from the message — goals and phases are not allowed there
2. 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)
3. Prefix informational lines with # so they are filtered out as comments
4. Put default goals/phases in the CI invocation or a shell alias instead of maven.config

Example fix

# .mvn/maven.config — before
-DskipTests=false
clean install

# .mvn/maven.config — after
-DskipTests=false

import java.nio.file.*;
import java.util.*;

// lint .mvn/maven.config: every line must be blank, a comment, or start with '-'
void lintMavenConfig(Path projectRoot) throws IOException {
    Path cfg = projectRoot.resolve(".mvn/maven.config");
    if (Files.isRegularFile(cfg)) {
        try (var lines = Files.lines(cfg)) {
            List<String> bad = lines.map(String::trim)
                    .filter(l -> !l.isEmpty() && !l.startsWith("#") && !l.startsWith("-"))
                    .toList();
            if (!bad.isEmpty()) {
                throw new IllegalStateException(
                    "maven.config may contain options only; offending lines: " + bad);
            }
        }
    }
}

catch (ExitException e) { // after cliManager.parse inside MavenCli.cli(); catch ParseException when embedding
    if (e instanceof ParseException pe
            && pe.getMessage() != null && pe.getMessage().startsWith("Unrecognized maven.config file entries")) {
        // message lists the offending entries; strip them from .mvn/maven.config and rerun
        fixMavenConfigAndRetry(projectRoot);
    }
}

When it happens

Trigger: 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.

Common situations: 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 '#'.

Related errors

• Unbounded range: {}
• Ranges overlap: {}
• Range defies version ordering: {}
• -D%s system property is not set.
• Directory {} extracted from the -f/--file command-line argum

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