{"record":{"id":"2a11886c55711a41","repo":"aeron-io/aeron","slug":"port-out-of-range-port","errorCode":null,"errorMessage":"port out of range: {port}","messagePattern":"port out of range: (.+?)","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"aeron-driver/src/main/java/io/aeron/driver/media/NamedInterface.java","lineNumber":96,"sourceCode":"        if (trailing > 0)\n        {\n            if (trailing == 1 || str.charAt(nameEnd + 1) != ':')\n            {\n                throw parseException(str);\n            }\n\n            try\n            {\n                port = Integer.parseUnsignedInt(str, nameEnd + 2, str.length(), 10);\n            }\n            catch (final NumberFormatException e)\n            {\n                throw parseException(str, e);\n            }\n\n            if (port > 0xFFFF)\n            {\n                throw parseException(\"port out of range: \" + port);\n            }\n        }\n\n        return new NamedInterface(name, port);\n    }\n\n    private static IllegalArgumentException parseException(final String str)\n    {\n        return parseException(str, null);\n    }\n\n    private static IllegalArgumentException parseException(final String str, final Throwable cause)\n    {\n        return new IllegalArgumentException(\n            \"expected format is '{interface_name}' or '{interface_name}:port', but got \" +\n            (str == null ? null : '\\'' + str + '\\''),\n            cause);\n    }","sourceCodeStart":78,"sourceCodeEnd":114,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-driver/src/main/java/io/aeron/driver/media/NamedInterface.java#L78-L114","documentation":"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.","triggerScenarios":"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').","commonSituations":"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.","solutions":["Use a port between 1 and 65535: '{eth0}:40456'.","Check the source of the port value (env var, config file) for wrong units or stray digits.","Pick an ephemeral or registered port within the valid 16-bit range.","Pre-validate: parse the port as an int and assert 0 <= port <= 65535 before configuring the driver."],"exampleFix":"// before\ndriverContext.interfaceToBindForControl(\"{eth0}:70000\");\n// after\ndriverContext.interfaceToBindForControl(\"{eth0}:40456\");","handlingStrategy":"validation","validationCode":"int port = Integer.parseInt(portStr); if (port < 1 || port > 65535) { throw new IllegalArgumentException(\"port must be 1-65535, got: \" + port); }","typeGuard":"static boolean isLegalUdpPort(int port) { return port >= 1 && port <= 0xFFFF; }","tryCatchPattern":"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; }","preventionTips":["Clamp/validate ports to 1-65535 at config load time.","Check the unit of the value feeding the port field (avoid ms/pid confusion).","Log the fully assembled interface string at startup for diagnosability."],"tags":["java","aeron","config-parse","port"],"backgroundTag":"value-out-of-range","analyzedSha":"6d60124e15e35c11b49ba2e3c2c2858a09a18803","analyzedAt":"2026-09-12T11:17:07.683Z","contentChangedAt":"2026-09-12T11:17:07.683Z","schemaVersion":2},"datasetVersion":"2026-09-19T12:17:13.211Z"}