oracle/graal · error · IllegalArgumentException

Invalid includevirtualthreads setting {value}. Espresso only

Error message

Invalid includevirtualthreads setting {value}. Espresso only supports n currently.

What it means

The JDWP 'includevirtualthreads' key is parsed with yesOrNo(), so 'n' is accepted, but the implementation then unconditionally rejects 'y': Espresso's JDWP backend cannot yet debug virtual threads, so enabling the setting is an error rather than silently ignored.

Source

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

                        host = inputHost;
                        port = inputPort;
                        break;
                    case "transport":
                        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, //

View on GitHub (pinned to a66e9ccd1d)

Solutions

1. Remove includevirtualthreads=y or set it to n.
2. Debug virtual-thread logic on platform threads until the Espresso version supports it.
3. Update debugger launch templates used for Espresso.

Example fix

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

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

if (opts.contains("includevirtualthreads=y")) {
    opts = opts.replace(",includevirtualthreads=y", ""); // strip before launch
}

static boolean virtualThreadsSupported(String jdwp) {
    return !jdwp.matches("(?:.*,)?includevirtualthreads=y(?:,.*)?");
}

When it happens

Trigger: --java.JDWPOptions=...,includevirtualthreads=y. (includevirtualthreads=n is accepted and does nothing.)

Common situations: Copy-pasting a JDK 21-style -agentlib:jdwp string that includes includevirtualthreads=y; IDE debugger profiles generated for recent HotSpot.

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/479afbf27ddddf2e. Report an issue: GitHub.