apache/maven · error · IllegalArgumentException

Unrecognized entries in maven.config (${configFile}) file: $

Error message

Unrecognized entries in maven.config (${configFile}) file: ${goals}

What it means

.mvn/maven.config may contain only options, never goals or phases; after parsing the file MavenParser checks options.goals() and any leftover positional token means the file contains non-option entries, so the whole file is rejected with IllegalArgumentException naming the entries and file. Goals on the command line are the only supported place. A malformed line that the parser demotes to a positional goal triggers the same error.

Source

Thrown at impl/maven-cli/src/main/java/org/apache/maven/cling/invoker/mvn/MavenParser.java:86

            List<String> args =
                    lines.filter(arg -> !arg.isEmpty() && !arg.startsWith("#")).toList();
            return parseArgs("atFile", args);
        } catch (ParseException e) {
            throw new IllegalArgumentException(
                    "Failed to parse arguments from file (" + atFile + "): " + e.getMessage(), e.getCause());
        } catch (IOException e) {
            throw new IllegalStateException("Error reading config file: " + atFile, e);
        }
    }

    protected MavenOptions parseMavenConfigOptions(Path configFile) {
        try (Stream<String> lines = Files.lines(configFile, StandardCharsets.UTF_8)) {
            List<String> args =
                    lines.filter(arg -> !arg.isEmpty() && !arg.startsWith("#")).toList();
            MavenOptions options = parseArgs("maven.config", args);
            if (options.goals().isPresent()) {
                // This file can only contain options, not args (goals or phases)
                throw new IllegalArgumentException("Unrecognized entries in maven.config (" + configFile + ") file: "
                        + options.goals().get());
            }
            return options;
        } catch (ParseException e) {
            throw new IllegalArgumentException(
                    "Failed to parse arguments from maven.config file (" + configFile + "): " + e.getMessage(),
                    e.getCause());
        } catch (IOException e) {
            throw new IllegalStateException("Error reading config file: " + configFile, e);
        }
    }

    protected MavenOptions parseArgs(String source, List<String> args) throws ParseException {
        return CommonsCliMavenOptions.parse(source, args.toArray(new String[0]));
    }
}

View on GitHub (pinned to e4093d4e12)

Solutions

  1. Remove goals/phases from .mvn/maven.config and pass them on the mvn command line instead.
  2. Keep only recognized options in the file (-D, -P, -T, -U, -V, ...), each as its own line.
  3. Fix any malformed line the parser demoted to a goal (missing `-` prefix, option and value merged on one line).
  4. After editing, run `mvn -v` in the project to confirm the file is accepted.

Example fix

# before: .mvn/maven.config
clean
install
-DskipTests=true

# after: .mvn/maven.config (goals stay on the command line: mvn clean install)
-DskipTests=true
Defensive patterns

Strategy: validation

Validate before calling

for (String line : Files.readAllLines(configFile, StandardCharsets.UTF_8)) {
    String t = line.trim();
    if (t.isEmpty() || t.startsWith("#")) continue;
    if (!t.startsWith("-")) {
        throw new IllegalArgumentException("maven.config accepts options only, found: " + t);
    }
}

Prevention

When it happens

Trigger: Writing `clean install` into .mvn/maven.config; putting a profile name without `-P`; a line whose option syntax is broken so Commons CLI classifies it as a goal.

Common situations: Teams migrating wrapper scripts into maven.config and pasting the entire command including goals; adding goals 'for convenience'; appending entries without the leading dash.

Understand the failure class

Background: Config validation failed: what "invalid value for {key}" and settings-rejection errors mean across 19 open-source libraries — this error's family across 19 libraries.

Related errors

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