oracle/graal · error · IllegalArgumentException

Could not find option %s

Error message

Could not find option %s

What it means

LibGraalSupportImpl.notifyOptions forwards each entry of a settings map to RuntimeOptions. Every key that does not start with 'X' followed by an empty value must match a registered RuntimeOptions descriptor; otherwise it throws IllegalArgumentException('Could not find option ' + name). This is strict option-name validation before any value conversion happens.

Source

Thrown at compiler/src/jdk.graal.compiler.libgraal/src/jdk/graal/compiler/libgraal/LibGraalSupportImpl.java:193

    /**
     * The set of libgraal options seen on the command line.
     */
    static EconomicSet<String> explicitOptions = EconomicSet.create();

    @Override
    public void notifyOptions(EconomicMap<String, String> settings) {
        MapCursor<String, String> cursor = settings.getEntries();
        while (cursor.advance()) {
            String name = cursor.getKey();
            String stringValue = cursor.getValue();
            Object value;
            if (name.startsWith("X") && stringValue.isEmpty()) {
                name = name.substring(1);
                value = stringValue;
            } else {
                RuntimeOptions.Descriptor desc = RuntimeOptions.getDescriptor(name);
                if (desc == null) {
                    throw new IllegalArgumentException("Could not find option " + name);
                }
                value = desc.convertValue(stringValue);
                explicitOptions.add(name);
            }
            try {
                RuntimeOptions.set(name, value);
            } catch (RuntimeException ex) {
                throw new IllegalArgumentException(ex);
            }
        }
    }

    @Override
    public void printOptions(PrintStream out, String namePrefix) {
        Comparator<RuntimeOptions.Descriptor> comparator = Comparator.comparing(RuntimeOptions.Descriptor::name);
        RuntimeOptions.listDescriptors().stream().sorted(comparator).forEach(d -> {
            String assign = explicitOptions.contains(d.name()) ? ":=" : "=";
            OptionValues.printHelp(out, namePrefix,

View on GitHub (pinned to a66e9ccd1d)

Solutions

1. Check the exact spelling against the libgraal option registry for your GraalVM version (e.g. via the options dump/print command your build exposes).
2. Remove or gate options that only exist in the Java-hosted compiler.
3. If the option is boolean-style, use the 'X'-prefixed key with an empty string value, which notifyOptions treats as a flag.
4. Upgrade/downgrade the caller and libgraal image to matching versions so the option sets align.

Example fix

// before
settings.put("NonExistentGraalOption", "true");
// after (registered name, or a flag via the X convention)
settings.put("XSomeBooleanBehavior", "");

// Before notifyOptions: filter unknown keys
MapCursor<String, String> c = settings.getEntries();
while (c.advance()) {
    String k = c.getKey();
    boolean isFlag = k.startsWith("X") && c.getValue().isEmpty();
    if (!isFlag && RuntimeOptions.getDescriptor(k) == null) {
        throw new IllegalArgumentException("Rejecting unknown option early: " + k);
    }
}

try {
    support.notifyOptions(settings);
} catch (IllegalArgumentException e) {
    // message names the offending option; strip or correct it and retry once
    if (e.getMessage() != null && e.getMessage().startsWith("Could not find option")) { /* drop key, re-run */ }
}

When it happens

Trigger: Calling the libgraal entry point with a settings/EconomicMap containing an option name that is not a registered libgraal RuntimeOption (typo, JVM-style '-XX:' flag name, or an option that only exists in the Java Graal compiler, not libgraal).

Common situations: Copying Java-mode Graal option names into native libgraal configuration; GraalVM version skew where an option was renamed or removed; passing boolean flags without the special 'X'+empty-value encoding.

Related errors

• OnShutdownCallback value does not have <classname>.<method n
• "%s" is not a valid option for %s. Valid values are %s
• "%s" is not a valid option for %s. Valid values are %s
• Non empty value required for option '%s'
• SpectrePHTBarriers can be set to 'AllTargets' if and only if

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