quarkusio/quarkus · error · IllegalStateException

Failed to parse Maven command line arguments

Error message

Failed to parse Maven command line arguments

What it means

BootstrapMavenOptionsParser.parse(args) mimics Maven's CLI parsing using a CLIManager (commons-cli based). If commons-cli throws a ParseException - an unrecognized option or a missing argument for an option that requires one - it throws IllegalStateException 'Failed to parse Maven command line arguments'.

Source

Thrown at independent-projects/bootstrap/maven-resolver/src/main/java/io/quarkus/bootstrap/resolver/maven/options/BootstrapMavenOptionsParser.java:102

                        if (parsedI < args.length) {
                            parsedValue = args[parsedI++];
                        } else {
                            break;
                        }
                    }
                }
            }
        }

        if (argsWoProps != null) {
            args = argsWoProps.toArray(new String[0]);
        }

        final CommandLine cmdLine;
        try {
            cmdLine = new CLIManager().parse(args);
        } catch (ParseException e) {
            throw new IllegalStateException("Failed to parse Maven command line arguments", e);
        }

        final Map<String, Object> map = new HashMap<>();
        put(cmdLine, map, CLIManager.ALTERNATE_USER_SETTINGS);
        put(cmdLine, map, CLIManager.ALTERNATE_GLOBAL_SETTINGS);
        put(cmdLine, map, CLIManager.ALTERNATE_POM_FILE);
        put(map, String.valueOf(CLIManager.ACTIVATE_PROFILES), cmdLine.getOptionValues(CLIManager.ACTIVATE_PROFILES));

        putBoolean(cmdLine, map, CLIManager.OFFLINE);
        putBoolean(cmdLine, map, CLIManager.SUPRESS_SNAPSHOT_UPDATES);
        putBoolean(cmdLine, map, CLIManager.UPDATE_SNAPSHOTS);
        putBoolean(cmdLine, map, CLIManager.CHECKSUM_FAILURE_POLICY);
        putBoolean(cmdLine, map, CLIManager.CHECKSUM_WARNING_POLICY);
        putBoolean(cmdLine, map, CLIManager.BATCH_MODE);
        putBoolean(cmdLine, map, CLIManager.NO_TRANSFER_PROGRESS);

        if (userProps != null) {
            put(map, String.valueOf(CLIManager.SET_SYSTEM_PROPERTY), userProps);

View on GitHub (pinned to e1c734241f)

Solutions

1. Read the wrapped ParseException cause - it names the unparsed option or missing argument - and correct that flag
2. Compare against `mvn --help` for the installed Maven version; remove or fix unsupported options
3. Ensure each option that takes a value is followed by it (e.g. -s /path/settings.xml, not just -s)
4. Validate the argument list before calling parse() by reusing the same CLIManager in a pre-check

Example fix

// before
parser.parse(new String[]{"-s"});  // -s requires a value
// after
parser.parse(new String[]{"-s", "/home/user/.m2/settings.xml"});

// Reject obviously malformed args before parsing
for (String arg : args) {
    if (arg.startsWith("-") && arg.length() > 1 && !arg.matches("-[a-zA-Z].*")) {
        throw new IllegalArgumentException("Suspicious option token: " + arg);
    }
}

try {
    Map<String, Object> opts = BootstrapMavenOptionsParser.parse(args);
} catch (IllegalStateException e) {
    log.error("Bad Maven CLI args " + Arrays.asList(args) + "; cause: " + e.getCause());
    throw e;
}

When it happens

Trigger: Passing args to BootstrapMavenOptionsParser.parse(String[]) that Maven's CLIManager cannot parse: an option unknown to that Maven version (e.g. -lll typo), an option missing its required value (e.g. -s without a path), or malformed grouped short options.

Common situations: Typos in flags handed to the bootstrap resolver, arguments from older/newer Maven versions not recognized by the embedded CLIManager, splitting a flag and its value into separate incorrectly ordered entries, whitespace/quoting issues upstream in parse().

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

• Invalid command line: ${cmdLine}
• unbalanced quotes in
• Failed
• Failed to parse MAVEN_OPTS=${mvnOpts}
• Failed to parse command line arguments ${Arrays.asList(args)

AI-assisted analysis of quarkusio/quarkus@e1c734241f (2026-09-05). Data as JSON: /api/errors/21f607aacbdf24ce. Report an issue: GitHub.