eclipse-vertx/vert.x · error · IllegalArgumentException

Invalid null value passed for traffic shaping options update

Error message

Invalid null value passed for traffic shaping options update

What it means

updateTrafficShapingOptions applies new channel traffic-shaping settings to a running (or starting) server; a null options object carries no update and is rejected. Vert.x throws IllegalArgumentException as an argument precondition. Passing an empty/default TrafficShapingOptions is fine — only null is invalid.

Source

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

  public int sniEntrySize() {
    return sslContextManager.sniEntrySize();
  }

  public Future<Boolean> updateSSLOptions(ServerSSLOptions options, boolean force) {
    NetServerImpl server = actualServer;
    if (server != null && server != this) {
      return server.updateSSLOptions(options, force);
    } else {
      ContextInternal ctx = vertx.getOrCreateContext();
      return sslContextProviderRef
        .update(options, ctx, force)
        .map(Objects::nonNull);
    }
  }

  public Future<Boolean> updateTrafficShapingOptions(TrafficShapingOptions options) {
    if (options == null) {
      throw new IllegalArgumentException("Invalid null value passed for traffic shaping options update");
    }
    NetServerImpl server = actualServer;
    ContextInternal ctx = vertx.getOrCreateContext();
    if (server == null) {
      // Server not yet started
      TrafficShapingOptions prev = this.config.getTrafficShapingOptions();
      boolean updated = prev == null || !prev.equals(options);
      this.config.setTrafficShapingOptions(options);
      return ctx.succeededFuture(updated);
    }
    // Update the traffic shaping options only for the actual/main server
    if (server != this) {
      return server.updateTrafficShapingOptions(options);
    } else {
      Promise<Boolean> promise = ctx.promise();
      ctx.emit(v -> updateTrafficShapingOptions(options, promise));
      return promise.future();
    }

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Only call the method with a non-null TrafficShapingOptions instance
2. Guard the call: if (options != null) server.updateTrafficShapingOptions(options)
3. Skip the update entirely when no shaping options are configured

Example fix

// before
server.updateTrafficShapingOptions(loadShapingOptions()); // IllegalArgumentException when null
// after
TrafficShapingOptions opts = loadShapingOptions();
if (opts != null) {
  server.updateTrafficShapingOptions(opts);
}

if (options != null) {
  server.updateTrafficShapingOptions(options);
}

try {
  server.updateTrafficShapingOptions(options);
} catch (IllegalArgumentException e) {
  // options was null: skip or substitute defaults
}

When it happens

Trigger: Calling server.updateTrafficShapingOptions(null), typically when the options come from optional config or a map lookup that returned null.

Common situations: Config-driven traffic shaping where the shaping section is absent; a cache of options returning null on first load; generic update paths that forward arbitrary option objects.

Related errors

• Invalid timer delay: ${delay}
• No null bind local address
• context must not be null
• blockedThreadCheckInterval must be > 0
• maxEventLoopExecuteTime must be > 0

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