oracle/graal · error · IllegalArgumentException

Invalid JDWP option: {key}. Supported options: 'transport',

Error message

Invalid JDWP option: {key}. Supported options: 'transport', 'address', 'server', 'suspend', and 'includevirtualthreads=n'.

What it means

The JDWP option parser switch only recognizes the keys transport, address, server, suspend, and includevirtualthreads. Any other key (e.g. 'launch', 'onthrow', 'timeout' supported by HotSpot JDWP) hits the default branch and throws with the list of supported keys.

Source

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

                        if (!"dt_socket".equals(value)) {
                            throw new IllegalArgumentException("Invalid transport " + value + ". Espresso only supports dt_socket currently.");
                        }
                        transport = value;
                        break;
                    case "server":
                        server = yesOrNo(key, value);
                        break;
                    case "suspend":
                        suspend = yesOrNo(key, value);
                        break;
                    case "includevirtualthreads":
                        boolean includevirtualthreads = yesOrNo(key, value);
                        if (includevirtualthreads) {
                            throw new IllegalArgumentException("Invalid includevirtualthreads setting " + value + ". Espresso only supports n currently.");
                        }
                        break;
                    default:
                        throw new IllegalArgumentException("Invalid JDWP option: " + key + ". Supported options: 'transport', 'address', 'server', 'suspend', and 'includevirtualthreads=n'.");
                }
            }
            return new JDWPOptions(transport, host, port, server, suspend);
        }
    });

    @Option(help = "JDWP agent Options. e.g. -agentlib:jdwp=transport=dt_socket,server=y,address=localhost:8000,suspend=y", //
                    category = OptionCategory.EXPERT, //
                    stability = OptionStability.STABLE, //
                    usageSyntax = "[transport=dt_socket],[server=y|n],[address=[<host>:]<port>,[suspend=y|n]]") //
    public static final OptionKey<JDWPOptions> JDWPOptions = new OptionKey<>(null, JDWP_OPTIONS_OPTION_TYPE);

    @Option(help = "Enable experimental java.lang.management APIs. Incur a bookkeeping overhead.", //
                    category = OptionCategory.EXPERT, //
                    stability = OptionStability.EXPERIMENTAL, //
                    usageSyntax = "true|false") //
    public static final OptionKey<Boolean> EnableManagement = new OptionKey<>(true);

View on GitHub (pinned to a66e9ccd1d)

Solutions

1. Strip unsupported keys; keep only transport, address, server, suspend, includevirtualthreads.
2. Maintain a separate debugger profile for Espresso vs HotSpot.
3. Filter known-unsupported keys programmatically before constructing the option.

Example fix

# before
--java.JDWPOptions=transport=dt_socket,server=y,address=:8000,timeout=5000

# after
--java.JDWPOptions=transport=dt_socket,server=y,address=:8000

Set<String> supported = Set.of("transport", "address", "server", "suspend", "includevirtualthreads");
for (String kv : opts.split(",")) {
    String key = kv.substring(0, kv.indexOf('='));
    if (!supported.contains(key)) throw new ConfigException("Unsupported JDWP key: " + key);
}

static boolean onlySupportedKeys(String s) {
    Set<String> ok = Set.of("transport","address","server","suspend","includevirtualthreads");
    for (String kv : s.split(",")) if (!ok.contains(kv.split("=",2)[0])) return false;
    return true;
}

When it happens

Trigger: --java.JDWPOptions=...,timeout=5000 or onthrow=... or launch=... - all valid HotSpot JDWP keys unsupported by Espresso.

Common situations: Forwarding full HotSpot agentlib strings (e.g. from IDE configs or JAVA_TOOL_OPTIONS) to Espresso; scripts shared between native JVM and Espresso launches.

Related errors

• Invalid JDWP option value: {key} can be only 'y' or 'n'.
• JDWP options must be a comma separated list of key=value pai
• Invalid JDWP option, address: {value}. Must be in the 0 - 65
• Invalid JDWP option, address: {value}. Port is not a number.
• Invalid transport {value}. Espresso only supports dt_socket

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