apache/maven · error · IllegalArgumentException

Failed to parse arguments from maven.config file (${configFi

Error message

Failed to parse arguments from maven.config file (${configFile}): ${message}

What it means

The contents of .mvn/maven.config (empty and `#` lines dropped, each line one argument) failed Commons CLI parsing in MavenParser.parseMavenConfigOptions. Same failure class as a bad command line, but the offending token lives in the per-project config file that is parsed on every build in that project. The message includes the file path and the ParseException reason.

Source

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

                    "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. Fix the token named by the ParseException text in the message.
2. Put option and value on separate lines (each line = exactly one argument).
3. Remove options not supported by the installed Maven version.
4. Validate edits with a cheap invocation (`mvn -v`) in the project directory.

Example fix

# before: .mvn/maven.config - one line is one argument, '-T 1C' is invalid
-T 1C

# after
-T
1C

try {
    new MavenParser().parseMavenConfigOptions(configFile);
} catch (IllegalArgumentException e) {
    // message names the file and the offending token
    reportConfigError(configFile, e.getMessage());
} catch (IllegalStateException e) {
    reportUnreadable(configFile, e);
}

When it happens

Trigger: An option and its value merged on one line (`-T 1C`), an unknown option for the installed Maven version, or an option missing its value inside .mvn/maven.config.

Common situations: Upgrading Maven majors and leaving removed flags in maven.config; copying options from blog posts that use shell syntax not valid line-per-argument format; different developers on different Maven versions sharing one config file.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• Unrecognized maven.config file entries: {}
• Failed to parse CLI arguments: ${message}
• Failed to parse arguments from file (${atFile}): ${message}
• Unrecognized entries in maven.config (${configFile}) file: $
• Error reading config file: ${configFile}

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