oracle/graal · error · IllegalArgumentException

JImage: Mode can be 'native', 'java'.

Error message

JImage: Mode can be 'native', 'java'.

What it means

The converter for --java.JImage maps the string to JImageMode.NATIVE/JAVA via valueOf; anything other than 'native' or 'java' (case-insensitive) throws. The option selects whether the module image (modules file of the JDK) is read by a native implementation or a Java one.

Source

Thrown at espresso/src/com.oracle.truffle.espresso/src/com/oracle/truffle/espresso/EspressoOptions.java:694

    @Option(help = "Use the host FinalReference to implement guest finalizers. If set to false, FinalReference will fallback to WeakReference semantics.", //
                    category = OptionCategory.EXPERT, //
                    stability = OptionStability.EXPERIMENTAL, //
                    usageSyntax = "false|true") //
    public static final OptionKey<Boolean> UseHostFinalReference = new OptionKey<>(true);

    public enum JImageMode {
        NATIVE,
        JAVA,
    }

    private static final OptionType<JImageMode> JIMAGE_MODE_OPTION_TYPE = new OptionType<>("JImageMode", new Function<String, JImageMode>() {
        @Override
        public JImageMode apply(String s) {
            try {
                return JImageMode.valueOf(s.toUpperCase(Locale.ROOT));
            } catch (IllegalArgumentException e) {
                throw new IllegalArgumentException("JImage: Mode can be 'native', 'java'.");
            }
        }
    });

    @Option(help = "Selects the jimage reader.", //
                    category = OptionCategory.EXPERT, stability = OptionStability.EXPERIMENTAL) //
    public static final OptionKey<JImageMode> JImage = new OptionKey<>(JImageMode.JAVA, JIMAGE_MODE_OPTION_TYPE);

    @Option(help = "Enables preview features.", //
                    category = OptionCategory.USER, //
                    stability = OptionStability.STABLE, //
                    usageSyntax = "false|true") //
    public static final OptionKey<Boolean> EnablePreview = new OptionKey<>(false);

    @Option(help = "Enables the WhiteBox API.", //
                    category = OptionCategory.INTERNAL, //
                    stability = OptionStability.EXPERIMENTAL, //
                    usageSyntax = "false|true") //

View on GitHub (pinned to a66e9ccd1d)

Solutions

1. Use --java.JImage=native or --java.JImage=java (default is java).
2. Omit the option unless you specifically need the native reader.
3. Check 'mx espresso' help output for current accepted values.

Example fix

# before
--java.JImage=system

# after
--java.JImage=native

if (!List.of("native", "java").contains(mode.toLowerCase(Locale.ROOT))) throw new ConfigException("JImage mode must be native|java");

static boolean validJImageMode(String s) { return s != null && s.matches("(?i)(native|java)"); }

When it happens

Trigger: Passing --java.JImage=both, system, or default; any string that is not one of the two enum names.

Common situations: Experimenting with expert options; config files carried over from other JVM distributions with similarly named flags.

Related errors

• --java.SpecCompliance: Mode can be 'strict' or 'hotspot'.
• -Xverify: Mode can be 'none', 'remote' or 'all'.
• --java.LivenessAnalysis can only be 'none'|'false', 'auto' o
• Not starting with digits: {size}
• Unit prefix can be at most one character: {size}

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