eclipse-vertx/vert.x · error · NullPointerException

No null bind local address

Error message

No null bind local address

What it means

listen(SocketAddress) requires an explicit bind address; passing null cannot be turned into a meaningful bind target inside the implementation. Vert.x throws NullPointerException with this message as a fail-fast precondition check rather than failing deep inside Netty at bind time.

Source

Thrown at vertx-core/src/main/java/io/vertx/core/net/impl/tcp/NetServerImpl.java:166

  }

  @Override
  public Future<Void> shutdown(Duration timeout) {
    ConnectionGroup group = channelGroup;
    if (group == null) {
      return vertx.getOrCreateContext().succeededFuture();
    }
    return group.shutdown(timeout);
  }

  @Override
  public Future<NetServer> listen(SocketAddress localAddress) {
    return listen(vertx.getOrCreateContext(), localAddress);
  }

  public Future<NetServer> listen(ContextInternal context, SocketAddress localAddress) {
    if (localAddress == null) {
      throw new NullPointerException("No null bind local address");
    }
    if (handler == null) {
      throw new IllegalStateException("Set connect handler first");
    }
    return bind(context, localAddress).map(this);
  }

  @Override
  public Future<NetServer> listen() {
    return listen(config.getPort(), config.getHost());
  }

  public boolean isClosed() {
    return !isListening();
  }

  private class NetSocketInitializer {

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Pass a real SocketAddress, e.g. SocketAddress.inetSocketAddress(port, host)
2. Default missing config to a concrete address such as new port with host "0.0.0.0"
3. Use the listen(int port) or listen() overloads when no explicit address object is needed

Example fix

// before
SocketAddress addr = parseAddress(config); // may return null
server.listen(addr); // NPE
// after
SocketAddress addr = parseAddress(config);
if (addr == null) addr = SocketAddress.inetSocketAddress(1234, "0.0.0.0");
server.listen(addr);

Objects.requireNonNull(addr, "bind address must not be null");
// or before building:
if (addr == null) addr = SocketAddress.inetSocketAddress(defaultPort, "0.0.0.0");

// Java has no type system null narrowing; use Objects.requireNonNull(addr)

try {
  server.listen(addr);
} catch (NullPointerException e) {
  // addr was null: fall back to default bind address
}

When it happens

Trigger: Passing a null SocketAddress to listen(SocketAddress) or listen(ContextInternal, SocketAddress), often from an uninitialized config field or a failed address-parsing step that returned null.

Common situations: Configuration where the host/port block is absent and the address is built as null; a resolver helper returning null on invalid input; forgetting the listen(port) convenience overload exists.

Related errors

• Invalid null value passed for traffic shaping options update
• context must not be null
• blockedThreadCheckInterval must be > 0
• maxEventLoopExecuteTime must be > 0
• maxWorkerpExecuteTime must be > 0

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