apache/maven · error · IllegalArgumentException

Failed to parse arguments from file (${atFile}): ${message}

Error message

Failed to parse arguments from file (${atFile}): ${message}

What it means

Maven supports @argfiles (`mvn @/path/to/file`); MavenParser.parseMavenAtFileOptions reads the file (empty and `#` lines dropped, each remaining line is one argument) and parses them with Commons CLI. This error means the arguments inside the file failed parsing - the same defect class as a bad command line, but hidden in the file. The atFile path and the ParseException reason are included in the message.

Source

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

        }
        return LayeredMavenOptions.layerMavenOptions(result);
    }

    protected MavenOptions parseMavenCliOptions(List<String> args) {
        try {
            return parseArgs(Options.SOURCE_CLI, args);
        } catch (ParseException e) {
            throw new IllegalArgumentException("Failed to parse CLI arguments: " + e.getMessage(), e.getCause());
        }
    }

    protected MavenOptions parseMavenAtFileOptions(Path atFile) {
        try (Stream<String> lines = Files.lines(atFile, StandardCharsets.UTF_8)) {
            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) {

View on GitHub (pinned to e4093d4e12)

Solutions

1. Open the file named in the message and fix the token the ParseException text points at.
2. Put each argument on its own line - never an option and its value on the same line.
3. Remove options that do not exist in the Maven version running the build.
4. Resave the file as plain UTF-8 without BOM, LF line endings, no smart quotes.
5. Prefer .mvn/maven.config for stable options and keep the @argfile only for per-run values.

Example fix

# before: build.args - one line = one argument, so '-T 1C' is one bad token
-T 1C
clean
package

# after: option and value on separate lines
-T
1C
clean
package

List<String> lines = Files.readAllLines(atFile, StandardCharsets.UTF_8).stream()
        .filter(l -> !l.isEmpty() && !l.startsWith("#")).toList();
for (String line : lines) {
    if (line.chars().anyMatch(Character::isWhitespace)) {
        throw new IllegalArgumentException("Argfile line carries more than one token: " + line);
    }
}

try {
    new MavenParser().parseMavenAtFileOptions(atFile);
} catch (IllegalArgumentException e) { /* parse error in file */ report(e); } catch (IllegalStateException e) { /* unreadable file */ report(e); }

When it happens

Trigger: An @argfile line carrying two tokens (e.g. `-T 1C` on one line, which is parsed as a single bogus argument since each line is exactly one argv entry), an unknown option, or an option missing its value inside the file.

Common situations: Argfiles shared across teams and Maven versions (an option removed in Maven 4 breaks the file); editors inserting a BOM or smart quotes; token/value pairs written on one line out of shell-script habit.

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

• Failed to parse CLI arguments: ${message}
• Error reading config file: ${atFile}
• Failed to parse command line options: ${message}
• Failed to parse command line options: {}
• Failed to parse command line options: {}

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