aeron-io/aeron · error · IllegalArgumentException

port out of range

Error message

port out of range: {port}

What it means

After successfully parsing the port, NamedInterface.parse() checks it against the maximum valid port value 0xFFFF (65535). A parsed port greater than 65535 cannot be a valid UDP port, so a dedicated 'port out of range' IllegalArgumentException is thrown.

Solutions

1. Use a port between 1 and 65535: '{eth0}:40456'.
2. Check the source of the port value (env var, config file) for wrong units or stray digits.
3. Pick an ephemeral or registered port within the valid 16-bit range.
4. Pre-validate: parse the port as an int and assert 0 <= port <= 65535 before configuring the driver.

Example fix

// before
driverContext.interfaceToBindForControl("{eth0}:70000");
// after
driverContext.interfaceToBindForControl("{eth0}:40456");

int port = Integer.parseInt(portStr); if (port < 1 || port > 65535) { throw new IllegalArgumentException("port must be 1-65535, got: " + port); }

static boolean isLegalUdpPort(int port) { return port >= 1 && port <= 0xFFFF; }

try { driver = MediaDriver.launch(ctx.interfaceToBindForControl(name + ":" + port)); } catch (IllegalArgumentException e) { if (e.getMessage().startsWith("port out of range")) { throw new ConfigException("configured port exceeds 65535: " + port, e); } throw e; }

When it happens

Trigger: Passing '{eth0}:70000' or any interface spec whose port exceeds 65535 (e.g. a substituted value in millions, or port shifted by concatenation like '{eth0}:404560').

Common situations: Unit confusion (e.g. milliseconds or a pid used as port); accidental digit concatenation when building the string; off-by-one with ephemeral port ranges documented in other units.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• endpoint has port=0 for send destination: channel=
• has port=0 for publication: channel=
• expected format is ' ' or ' :port', but got
• invalid port
• key length out of bounds

AI-assisted analysis of aeron-io/aeron@6d60124e15 (2026-09-12). Data as JSON: /api/errors/2a11886c55711a41. Report an issue: GitHub.

Appendix: source

Thrown at aeron-driver/src/main/java/io/aeron/driver/media/NamedInterface.java:96

        if (trailing > 0)
        {
            if (trailing == 1 || str.charAt(nameEnd + 1) != ':')
            {
                throw parseException(str);
            }

            try
            {
                port = Integer.parseUnsignedInt(str, nameEnd + 2, str.length(), 10);
            }
            catch (final NumberFormatException e)
            {
                throw parseException(str, e);
            }

            if (port > 0xFFFF)
            {
                throw parseException("port out of range: " + port);
            }
        }

        return new NamedInterface(name, port);
    }

    private static IllegalArgumentException parseException(final String str)
    {
        return parseException(str, null);
    }

    private static IllegalArgumentException parseException(final String str, final Throwable cause)
    {
        return new IllegalArgumentException(
            "expected format is '{interface_name}' or '{interface_name}:port', but got " +
            (str == null ? null : '\'' + str + '\''),
            cause);
    }

View on GitHub (pinned to 6d60124e15)