eclipse-vertx/vert.x · error · java.lang.IllegalArgumentException

port out of range:${port}

Error message

port out of range:${port}

What it means

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.

Source

Thrown at vertx-core/src/main/java/io/vertx/core/datagram/impl/DatagramSocketImpl.java:289

            if (res2.isSuccess()) {
              metrics.listening(local.host(), localAddress());
            }
          });
        }
        f2.addListener(promise);
      } else {
        promise.fail(res1.cause());
      }
    });
    return promise.future().map(this);
  }

  @Override
  public Future<Void> send(Buffer packet, int port, String host) {
    Objects.requireNonNull(packet, "no null packet accepted");
    Objects.requireNonNull(host, "no null host accepted");
    if (port < 0 || port > 65535) {
      throw new IllegalArgumentException("port out of range:" + port);
    }
    NameResolver resolver = context.owner().nameResolver();
    PromiseInternal<Void> promise = context.promise();
    io.netty.util.concurrent.Future<InetSocketAddress> f1 = resolver.resolve(context.nettyEventLoop(), host);
    f1.addListener((GenericFutureListener<io.netty.util.concurrent.Future<InetSocketAddress>>) res1 -> {
      if (res1.isSuccess()) {
        ChannelFuture f2 = channel.writeAndFlush(new DatagramPacket(((BufferInternal)packet).getByteBuf(), new InetSocketAddress(f1.getNow().getAddress(), port)));
        if (metrics != null) {
          f2.addListener(fut -> {
            if (fut.isSuccess()) {
              metrics.bytesWritten(null, SocketAddress.inetSocketAddress(port, host), packet.length());
            }
          });
        }
        f2.addListener(promise);
      } else {
        promise.fail(res1.cause());
      }

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Pass a port in 0..65535; clamp or validate: if (port < 0 || port > 65535) fail before calling send().
2. Fix the port source (config/env parse) and use an Integer.parseInt with range check, or a typed Port value class.
3. Replace -1 sentinels with Optional/absent handling that skips the send instead of calling it.

Example fix

// before
socket.send(packet, port, host); // port could be -1 or 70000
// after
Objects.checkIndex? no; validate:
if (port < 0 || port > 65535) throw new IllegalArgumentException("invalid UDP port: " + port);
socket.send(packet, port, host);

if (port < 0 || port > 65535) throw new IllegalArgumentException("UDP port out of range: " + port);
socket.send(packet, port, host);

static boolean isValidPort(int port) { return port >= 0 && port <= 65535; }

try {
  socket.send(packet, port, host);
} catch (IllegalArgumentException e) {
  log.error("Cannot send datagram: {}", e.getMessage());
}

When it happens

Trigger: 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.

Common situations: 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.

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

• blockedThreadCheckInterval must be > 0
• maxEventLoopExecuteTime must be > 0
• maxWorkerpExecuteTime must be > 0
• internalBlockingPoolSize must be > 0
• quorumSize should be >= 1

AI-assisted analysis of eclipse-vertx/vert.x@fb308bd8c3 (2026-09-06). Data as JSON: /api/errors/6a627ec0316c7189. Report an issue: GitHub.