{"record":{"id":"6a627ec0316c7189","repo":"eclipse-vertx/vert.x","slug":"port-out-of-range-port","errorCode":null,"errorMessage":"port out of range:${port}","messagePattern":"port out of range:(.+?)","errorType":"exception","errorClass":"java.lang.IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"vertx-core/src/main/java/io/vertx/core/datagram/impl/DatagramSocketImpl.java","lineNumber":289,"sourceCode":"            if (res2.isSuccess()) {\n              metrics.listening(local.host(), localAddress());\n            }\n          });\n        }\n        f2.addListener(promise);\n      } else {\n        promise.fail(res1.cause());\n      }\n    });\n    return promise.future().map(this);\n  }\n\n  @Override\n  public Future<Void> send(Buffer packet, int port, String host) {\n    Objects.requireNonNull(packet, \"no null packet accepted\");\n    Objects.requireNonNull(host, \"no null host accepted\");\n    if (port < 0 || port > 65535) {\n      throw new IllegalArgumentException(\"port out of range:\" + port);\n    }\n    NameResolver resolver = context.owner().nameResolver();\n    PromiseInternal<Void> promise = context.promise();\n    io.netty.util.concurrent.Future<InetSocketAddress> f1 = resolver.resolve(context.nettyEventLoop(), host);\n    f1.addListener((GenericFutureListener<io.netty.util.concurrent.Future<InetSocketAddress>>) res1 -> {\n      if (res1.isSuccess()) {\n        ChannelFuture f2 = channel.writeAndFlush(new DatagramPacket(((BufferInternal)packet).getByteBuf(), new InetSocketAddress(f1.getNow().getAddress(), port)));\n        if (metrics != null) {\n          f2.addListener(fut -> {\n            if (fut.isSuccess()) {\n              metrics.bytesWritten(null, SocketAddress.inetSocketAddress(port, host), packet.length());\n            }\n          });\n        }\n        f2.addListener(promise);\n      } else {\n        promise.fail(res1.cause());\n      }","sourceCodeStart":271,"sourceCodeEnd":307,"githubUrl":"https://github.com/eclipse-vertx/vert.x/blob/fb308bd8c3f12c79f4ae89bef67fadf6c80d036e/vertx-core/src/main/java/io/vertx/core/datagram/impl/DatagramSocketImpl.java#L271-L307","documentation":"DatagramSocketImpl.send(Buffer, int port, String host) throws IllegalArgumentException with \"port out of range:<port>\" when the destination port is negative or greater than 65535. UDP ports are 16-bit unsigned; anything outside 0..65535 cannot be encoded in a sockaddr_in. The check runs before DNS resolution so an invalid port fails immediately and synchronously.","triggerScenarios":"socket.send(packet, 70000, \"host\") or send(packet, -1, \"host\"); a destination port parsed from config/CLI as an int beyond 16 bits; a port variable defaulted to -1 as a 'not set' sentinel then passed straight to send.","commonSituations":"Config files or env vars containing an out-of-range port typo; using a 32-bit 'service id' instead of the actual UDP port; forgetting to replace a -1 default with the resolved port; off-by-design reuse of TCP code that allowed 65536+ in tests.","solutions":["Pass a port in 0..65535; clamp or validate: if (port < 0 || port > 65535) fail before calling send().","Fix the port source (config/env parse) and use an Integer.parseInt with range check, or a typed Port value class.","Replace -1 sentinels with Optional/absent handling that skips the send instead of calling it."],"exampleFix":"// before\nsocket.send(packet, port, host); // port could be -1 or 70000\n// after\nObjects.checkIndex? no; validate:\nif (port < 0 || port > 65535) throw new IllegalArgumentException(\"invalid UDP port: \" + port);\nsocket.send(packet, port, host);","handlingStrategy":"validation","validationCode":"if (port < 0 || port > 65535) throw new IllegalArgumentException(\"UDP port out of range: \" + port);\nsocket.send(packet, port, host);","typeGuard":"static boolean isValidPort(int port) { return port >= 0 && port <= 65535; }","tryCatchPattern":"try {\n  socket.send(packet, port, host);\n} catch (IllegalArgumentException e) {\n  log.error(\"Cannot send datagram: {}\", e.getMessage());\n}","preventionTips":["Parse ports with a validated helper that enforces 0..65535 at the config boundary","Never use -1 as a port sentinel; use Optional<Integer>","Store ports as a small value type (e.g. record Port(int value)) that validates on construction"],"tags":["vertx","datagram","udp","port-validation"],"backgroundTag":"value-out-of-range","analyzedSha":"fb308bd8c3f12c79f4ae89bef67fadf6c80d036e","analyzedAt":"2026-09-06T11:37:12.241Z","contentChangedAt":"2026-09-06T11:37:12.241Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}