oracle/graal · error · IllegalArgumentException

Could not find option %s (alternates: Option PrintGraphFile

Error message

Could not find option %s (alternates: Option PrintGraphFile has been removed - use PrintGraph=File instead; %nDid you mean one of the following?%n    %s=<value>)

What it means

Thrown by OptionsParser.parseOptions when an option name is not found among the OptionDescriptors supplied by the loader. Before failing it runs fuzzyMatch to suggest close names, and it special-cases the removed 'PrintGraphFile' option to point at its replacement 'PrintGraph=File'. This is the standard 'unknown Graal option' error developers see with -Dgraal.* flags.

Source

Thrown at compiler/src/jdk.graal.compiler.options/src/jdk/graal/compiler/options/OptionsParser.java:211

     */
    public static void parseOption(String name, Object uncheckedValue, EconomicMap<OptionKey<?>, Object> values, Iterable<OptionDescriptors> loader) {

        OptionDescriptor desc = lookup(loader, name);
        if (desc == null) {
            Formatter msg = new Formatter();
            if (name.equals("PrintGraphFile")) {
                msg.format("Option PrintGraphFile has been removed - use PrintGraph=File instead");
            } else {
                List<OptionDescriptor> matches = fuzzyMatch(loader, name);
                msg.format("Could not find option %s", name);
                if (!matches.isEmpty()) {
                    msg.format("%nDid you mean one of the following?");
                    for (OptionDescriptor match : matches) {
                        msg.format("%n    %s=<value>", match.getName());
                    }
                }
            }
            throw new IllegalArgumentException(msg.toString());
        }

        Object value = parseOptionValue(desc, uncheckedValue);

        desc.getOptionKey().update(values, value);
    }

    /**
     * Parses a given option value with a known descriptor.
     */
    public static Object parseOptionValue(OptionDescriptor desc, Object uncheckedValue) {
        Class<?> optionType = desc.getOptionValueType();
        Object value;
        if (!(uncheckedValue instanceof String valueString)) {
            if (optionType != uncheckedValue.getClass()) {
                String type = optionType.getSimpleName();
                throw new IllegalArgumentException(type + " option '" + desc.getName() + "' must have " + type + " value, not " + uncheckedValue.getClass() + " [toString: " + uncheckedValue + "]");
            }

View on GitHub (pinned to a66e9ccd1d)

Solutions

Read the suggestions in the message ('Did you mean one of the following?') and switch to the suggested exact name.
If the option is PrintGraphFile, replace it with PrintGraph=File as the message instructs.
Verify the option exists in your Graal version: check the options table via mx options or the GraalVM docs for the exact release.
Ensure the right OptionDescriptor loader (suite/classpath) is in scope when parsing programmatically.

Example fix

// before
-Dgraal.PrintGraphFile=true

// after
-Dgraal.PrintGraph=File

Defensive patterns

Strategy: validation

Validate before calling

boolean optionExists(OptionDescriptorLoader loader, String name) {
    return lookupOption(loader, name) != null;
}

String name = setting.substring(0, setting.indexOf('='));
if (!optionExists(loader, name)) {
    throw new ConfigException("Unknown Graal option '" + name + "' for this build");
}
OptionsParser.parseOptions(...);

Try / catch

try {
    OptionsParser.parseOptions(settings, values, loader);
} catch (IllegalArgumentException e) {
    if (e.getMessage().startsWith("Could not find option") || e.getMessage().contains("has been removed")) {
        log.warn("Skipping unknown Graal option: {}", e.getMessage());
        return; // or collect and report
    }
    throw e;
}

Prevention

Pin the GraalVM version in CI so option sets match documentation.
Validate -Dgraal.* flags in a smoke-test JVM startup step before deployment.
When upgrading, diff the option list (mx options) between old and new versions.

When it happens

Trigger: Calling parseOptions with e.g. 'PrintGraphFile=true' (removed option), or a typo like 'PrintGrahp=false', or an option that exists in a different Graal build/suite than the one whose OptionDescriptor loader is passed in. The lookup is scoped to the descriptors the loader exposes, so a valid option can still fail if the loader lacks it.

Common situations: Upgrading GraalVM/JDK where an option was renamed or removed (PrintGraphFile is the canonical case); copying -Dgraal flags from documentation for a different Graal version; using an option that only exists in libgraal vs. compiler-only configurations; typos in long option names in launcher scripts.

Related errors

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