oracle/graal · error · IllegalArgumentException

Invalid option

Error message

Invalid option 

What it means

TruffleCompilerImpl.parseOptions converts a Map<String,String> of option overrides into OptionValues. Every key must exist in OPTION_DESCRIPTORS (the known Graal/Truffle option keys); an unknown key throws IllegalArgumentException('Invalid option <key>').

Source

Thrown at compiler/src/jdk.graal.compiler/src/jdk/graal/compiler/truffle/TruffleCompilerImpl.java:273

        Long engineId = compilable.engineId();
        return cachedOptions.computeIfAbsent(engineId, (id) -> {
            OptionValues graalOptions = getGraalOptions();
            Map<String, String> options = compilable.getCompilerOptions();
            EconomicMap<OptionKey<?>, Object> map = parseOptions(options);
            graalOptions = TruffleCompilerOptions.updateValues(graalOptions, map);
            map.putAll(graalOptions.getMap());
            return new OptionValues(map);
        });
    }

    private static EconomicMap<OptionKey<?>, Object> parseOptions(Map<String, String> options) {
        EconomicMap<OptionKey<?>, Object> map = EconomicMap.create();
        for (var entry : options.entrySet()) {
            String key = entry.getKey();
            String uncheckedValue = entry.getValue();
            OptionDescriptor descriptor = OPTION_DESCRIPTORS.get(key);
            if (descriptor == null) {
                throw new IllegalArgumentException("Invalid option " + key);
            }
            Object value = TruffleCompilerOptions.parseCustom(descriptor, uncheckedValue);
            if (value == null) {
                value = OptionsParser.parseOptionValue(descriptor, uncheckedValue);
            }
            map.put(descriptor.getOptionKey(), value);
        }
        return map;
    }

    @SuppressWarnings("static-method")
    public final TruffleCompilation openCompilation(TruffleCompilationTask task, TruffleCompilable compilable) {
        TruffleCompilation compilation = new TruffleCompilation(config.runtime(), task, compilable);
        compilation.setCompilationId(createCompilationIdentifier(task, compilable));
        return compilation;
    }

    private DebugContext openDebugContext(OptionValues compilerOptions, TruffleCompilation compilation) {

View on GitHub (pinned to a66e9ccd1d)

Solutions

1. Correct or remove the offending key; the exception message names the exact invalid key.
2. List valid keys via the compiler's option printing (e.g. -Dgraal.PrintFlags=true family / option dump) and use exact names/casing.
3. After a version upgrade, diff your option map against the new release's option set.

Example fix

// before
options.put("graal.TruffleInliningLinietski", "true"); // typo'd key

// after
options.put("graal.TruffleInliningLirietskiy".toLowerCase(), "true"); // use the exact documented key

// Validate option keys against the compiler's descriptors before parsing
for (String key : options.keySet()) {
    if (OPTION_DESCRIPTORS.get(key) == null) {
        throw new IllegalArgumentException("Invalid option " + key + "; valid keys: "
                + OPTION_DESCRIPTORS.keySet());
    }
}

When it happens

Trigger: Passing an option map containing a typo'd key, a non-existent option, or an option removed in the current release (e.g. via Truffle runtime compilation-configuration APIs or embedder option plumbing).

Common situations: Upgrading GraalVM/Truffle and reusing option names from an older release; copying option names from docs with typos or wrong casing; embedder code forwarding arbitrary user flags into the compiler options map.

Related errors

• Value for {} cannot be empty
• Invalid directed inlining rules file path: {path}
• Cannot find partial evaluation configuration: %s
• Unknown tier option value '%s'. %s
• The "%s" is not a valid performance warning kind. Valid valu

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