oracle/graal · error · IllegalArgumentException

Invalid JDWP option, address: {value}. Must be in the 0 - 65

Error message

Invalid JDWP option, address: {value}. Must be in the 0 - 65535 range.

What it means

While parsing the JDWP 'address' key, the port component (text after the first ':') is parsed as a long; if the numeric value is <0 or >65535 an IllegalArgumentException is thrown because it is not a valid TCP port.

Source

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

                    throw new IllegalArgumentException("JDWP options must be a comma separated list of key=value pairs.");
                }
                String key = keyValue.substring(0, equalsIndex);
                String value = keyValue.substring(equalsIndex + 1);
                switch (key) {
                    case "address":
                        String inputHost = null;
                        int inputPort = 0;
                        if (!value.isEmpty()) {
                            int colonIndex = value.indexOf(':');
                            if (colonIndex > 0) {
                                inputHost = value.substring(0, colonIndex);
                            }
                            String portStr = value.substring(colonIndex + 1);
                            long realValue;
                            try {
                                realValue = Long.valueOf(portStr);
                                if (realValue < 0 || realValue > 65535) {
                                    throw new IllegalArgumentException("Invalid JDWP option, address: " + value + ". Must be in the 0 - 65535 range.");
                                }
                            } catch (NumberFormatException ex) {
                                throw new IllegalArgumentException("Invalid JDWP option, address: " + value + ". Port is not a number. Must be a number in the 0 - 65535 range.");
                            }
                            inputPort = (int) realValue;
                        }
                        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;

View on GitHub (pinned to a66e9ccd1d)

Solutions

Use a port in 0-65535, e.g. address=localhost:8000.
If the port comes from a variable, clamp/validate it before launch.
Use port 0 to let the OS assign a free port.

Example fix

# before
--java.JDWPOptions=transport=dt_socket,server=y,address=localhost:80000

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

Defensive patterns

Strategy: validation

Validate before calling

int port = Integer.parseInt(portStr);
if (port < 0 || port > 65535) throw new ConfigException("Port out of range: " + port);

Type guard

static boolean validPort(String p) {
    if (!p.matches("\\d+")) return false;
    long v = Long.parseLong(p);
    return v >= 0 && v <= 65535;
}

Prevention

Validate ports at config-parse time, not launch time.
Prefer port 0 + reading the assigned port for dynamic setups.

When it happens

Trigger: --java.JDWPOptions=...,address=localhost:70000 or address=:99999; also negative ports like address=host:-1.

Common situations: Ports computed from environment variables or dynamically allocated colliding with the range check; typos adding an extra digit; copying an ephemeral port report incorrectly.

Related errors

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