{"record":{"id":"1bd5274c5fab1cbd","repo":"apache/maven","slug":"failed-to-parse-cli-arguments-message","errorCode":null,"errorMessage":"Failed to parse CLI arguments: ${message}","messagePattern":"Failed to parse CLI arguments: (.+?)","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"impl/maven-cli/src/main/java/org/apache/maven/cling/invoker/mvn/MavenParser.java","lineNumber":62,"sourceCode":"            if (Files.isRegularFile(file)) {\n                result.add(parseMavenAtFileOptions(file));\n            } else {\n                throw new IllegalArgumentException(\"Specified file does not exists (\" + file + \")\");\n            }\n        }\n        // maven.config; if exists\n        Path mavenConfig = context.rootDirectory != null ? context.rootDirectory.resolve(\".mvn/maven.config\") : null;\n        if (mavenConfig != null && Files.isRegularFile(mavenConfig)) {\n            result.add(parseMavenConfigOptions(mavenConfig));\n        }\n        return LayeredMavenOptions.layerMavenOptions(result);\n    }\n\n    protected MavenOptions parseMavenCliOptions(List<String> args) {\n        try {\n            return parseArgs(Options.SOURCE_CLI, args);\n        } catch (ParseException e) {\n            throw new IllegalArgumentException(\"Failed to parse CLI arguments: \" + e.getMessage(), e.getCause());\n        }\n    }\n\n    protected MavenOptions parseMavenAtFileOptions(Path atFile) {\n        try (Stream<String> lines = Files.lines(atFile, StandardCharsets.UTF_8)) {\n            List<String> args =\n                    lines.filter(arg -> !arg.isEmpty() && !arg.startsWith(\"#\")).toList();\n            return parseArgs(\"atFile\", args);\n        } catch (ParseException e) {\n            throw new IllegalArgumentException(\n                    \"Failed to parse arguments from file (\" + atFile + \"): \" + e.getMessage(), e.getCause());\n        } catch (IOException e) {\n            throw new IllegalStateException(\"Error reading config file: \" + atFile, e);\n        }\n    }\n\n    protected MavenOptions parseMavenConfigOptions(Path configFile) {\n        try (Stream<String> lines = Files.lines(configFile, StandardCharsets.UTF_8)) {","sourceCodeStart":44,"sourceCodeEnd":80,"githubUrl":"https://github.com/apache/maven/blob/e4093d4e120eac99d6bdce5ba67cace2f3085c97/impl/maven-cli/src/main/java/org/apache/maven/cling/invoker/mvn/MavenParser.java#L44-L80","documentation":"Thrown by the Maven CLI launcher (cling) when Apache Commons CLI reports a ParseException while parsing the raw `mvn` command line (parseArgs with Options.SOURCE_CLI). It means a malformed or unknown option: an option that needs a value got none, an unrecognized flag was passed, or a token starting with `-` could not be matched. The underlying ParseException message is appended and the result rethrown as IllegalArgumentException from MavenParser.parseMavenCliOptions.","triggerScenarios":"Calling `mvn -T` without a thread-count value (the next token is swallowed or missing), passing an unknown flag like `--teer`, giving `-Dmaven.test.skip` without `=value`, or letting a wrapper script/IDE inject a flag removed in the installed Maven version.","commonSituations":"Typos in -D/-P/-T flags; shell quoting that splits `key=value` into two argv tokens; migrating Maven 3 builds to Maven 4 where old flags were removed; CI scripts reusing stale option names; options accidentally placed after `--`.","solutions":["Fix the exact option named in the appended ParseException text (e.g. `mvn -T 1C clean install` instead of `mvn -T clean install`).","Run `mvn -h` to confirm the option exists in the installed Maven version and note its argument requirements.","Quote -D properties so the shell keeps key=value in one token: `mvn '-DskipTests=true' package`.","Audit @argfiles and .mvn/maven.config referenced by the command, since the same bad option may come from there.","Replace Maven 3 flags removed in Maven 4 with their current equivalents."],"exampleFix":"# before: -T has no value, 'clean' is consumed as its argument\nmvn -T clean install\n\n# after: thread count supplied explicitly\nmvn -T 1C clean install","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n    MavenOptions options = parser.parseMavenCliOptions(args);\n} catch (IllegalArgumentException e) {\n    if (e.getMessage() != null && e.getMessage().startsWith(\"Failed to parse CLI arguments\")) {\n        // message carries the Commons CLI reason; report usage, do not retry\n        throw new UsageException(e.getMessage(), e);\n    }\n    throw e;\n}","preventionTips":["Validate generated command lines against `mvn -h` for the target Maven version before shipping scripts.","Keep `key=value` pairs inside one shell token.","Pin the Maven major version in CI so removed options fail at setup, not mid-script."],"tags":["maven","cli","argument-parsing","commons-cli"],"backgroundTag":"cli-argument-parsing-failed","analyzedSha":"e4093d4e120eac99d6bdce5ba67cace2f3085c97","analyzedAt":"2026-08-21T22:58:24.034Z","schemaVersion":2},"datasetVersion":"2026-08-21T23:17:16.201Z"}