oracle/graal · error · UnknownArgumentException

Unknown option '%s'.

Error message

Unknown option '%s'.

What it means

Thrown by ArgumentParser.parse when a command-line token starting with '--' does not match any option argument registered for the current command. The whole token up to the first '=' is used as the lookup key, so both a misspelled flag and a completely unknown flag trigger it. It surfaces as UnknownArgumentException from profdiff's argument-parsing layer.

Source

Thrown at compiler/src/org.graalvm.profdiff/src/org/graalvm/profdiff/args/ArgumentParser.java:82

     *
     * @param args the list of program arguments
     * @throws InvalidArgumentException the provided argument has an invalid value
     * @throws MissingArgumentException a required argument is missing in the program arguments
     * @throws UnknownArgumentException a value was provided for an unknown argument
     */
    public void parse(String[] args) throws InvalidArgumentException,
                    MissingArgumentException,
                    UnknownArgumentException {
        int nextPositionalArg = 0;
        for (int index = 0; index < args.length;) {
            String arg = args[index];
            Argument argument;
            if (arg.startsWith(Argument.OPTION_PREFIX)) {
                int equalSignIndex = arg.indexOf(Argument.EQUAL_SIGN);
                String optionArgumentName = equalSignIndex == -1 ? arg : arg.substring(0, equalSignIndex);
                argument = optionArguments.get(optionArgumentName);
                if (argument == null) {
                    throw new UnknownArgumentException(arg);
                }
            } else {
                if (nextPositionalArg >= positionalArguments.size()) {
                    throw new UnknownArgumentException(arg);
                }
                argument = positionalArguments.get(nextPositionalArg++);
            }
            index = argument.parse(args, index);
        }
        for (Argument argument : optionArguments.getValues()) {
            if (!argument.isSet() && argument.isRequired()) {
                throw new MissingArgumentException(argument.getName());
            }
        }
        if (nextPositionalArg < positionalArguments.size() && positionalArguments.get(nextPositionalArg).isRequired()) {
            throw new MissingArgumentException(positionalArguments.get(nextPositionalArg).getName());
        }
    }

View on GitHub (pinned to a66e9ccd1d)

Solutions

1. Re-run with the command's help output to list valid options and copy the exact spelling.
2. Check whether the option belongs to the subcommand you invoked; move it after the subcommand name.
3. If embedding ArgumentParser, register the option before parse() via the addArgument/addOption helpers so optionArguments contains the name.
4. If the flag worked before, diff your profdiff/GraalVM version's option list — the name may have changed.

Example fix

# before
mx profdiff --experiment1 out1 --experiment2 out2 --percentages=50
# after (use the real option names shown by 'mx profdiff --help')
mx profdiff --experiment1 out1 --experiment2 out2 --percentage 50

// Before calling parser.parse(args), check every '--' token against known options
Set<String> known = parser.getOptionArguments().keySet().stream().collect(java.util.stream.Collectors.toSet());
for (String a : args) {
    if (a.startsWith("--")) {
        String key = a.contains("=") ? a.substring(0, a.indexOf('=')) : a;
        if (!known.contains(key)) throw new IllegalArgumentException("Bad option: " + key);
    }
}

try {
    parser.parse(args);
} catch (UnknownArgumentException e) {
    System.err.println(e.getMessage());
    System.err.println(parser.getUsage()); // show valid options
    System.exit(1);
}

When it happens

Trigger: Calling ArgumentParser.parse(String[]) (directly, or via the profdiff CLI entry) with a token like '--verbsoe' or '--foo=bar' where 'optionArguments.get("--foo")' returns null. Also triggered by options that belong to a different subcommand than the one being invoked.

Common situations: Typos in profdiff options (e.g. '--out-format' vs the real '--out' spelling), copying a flag from an older/newer profdiff version where it was renamed, using a subcommand-specific option before/without selecting that subcommand, or passing JVM flags to the profdiff argument parser instead of to the VM.

Related errors

• The argument '%s' is required.
• The argument '%s' could not be parsed: expected true or fals
• The argument '%s' could not be parsed: invalid command name:
• Unknown argument: %s
• no value provided

AI-assisted analysis of oracle/graal@a66e9ccd1d (2026-08-14). Data as JSON: /api/errors/fb1dc0518f890f66. Report an issue: GitHub.