eclipse-vertx/vert.x · error · IllegalArgumentException

Could not find network interface with name ${options.getMult

Error message

Could not find network interface with name ${options.getMulticastNetworkInterface()}

What it means

Thrown by Transport.configure when configuring a DatagramSocket's channel with the multicast network interface name set in DatagramSocketOptions. NetworkInterface.getByName() returned null or threw SocketException, meaning no NIC matches the configured name, so Vert.x rejects the options with an IllegalArgumentException rather than silently ignoring multicast configuration.

Source

Thrown at vertx-core/src/main/java/io/vertx/core/spi/transport/Transport.java:140

    if (options.getReceiveBufferSize() != -1) {
      channel.config().setReceiveBufferSize(options.getReceiveBufferSize());
      channel.config().setRecvByteBufAllocator(new FixedRecvByteBufAllocator(options.getReceiveBufferSize()));
    }
    channel.config().setOption(ChannelOption.SO_REUSEADDR, options.isReuseAddress());
    if (options.getTrafficClass() != -1) {
      channel.config().setTrafficClass(options.getTrafficClass());
    }
    channel.config().setBroadcast(options.isBroadcast());
    if (this instanceof NioTransport) {
      channel.config().setLoopbackModeDisabled(options.isLoopbackModeDisabled());
      if (options.getMulticastTimeToLive() != -1) {
        channel.config().setTimeToLive(options.getMulticastTimeToLive());
      }
      if (options.getMulticastNetworkInterface() != null) {
        try {
          channel.config().setNetworkInterface(NetworkInterface.getByName(options.getMulticastNetworkInterface()));
        } catch (SocketException e) {
          throw new IllegalArgumentException("Could not find network interface with name " + options.getMulticastNetworkInterface());
        }
      }
    }
  }

  default void configure(TcpConfig config, boolean domainSocket, Bootstrap bootstrap) {
    if (!domainSocket) {
      NioTransport.configOption(bootstrap, config, TcpOption.NODELAY, ChannelOption.TCP_NODELAY);
      bootstrap.option(ChannelOption.SO_KEEPALIVE, config.isSoKeepAlive());
    }
    if (config.getSoLinger() != -1) {
      bootstrap.option(ChannelOption.SO_LINGER, config.getSoLinger());
    }
  }

  default void configure(TcpConfig config, boolean domainSocket, ServerBootstrap bootstrap) {
    if (!domainSocket) {
      NioTransport.configChildOption(bootstrap, config, TcpOption.NODELAY, ChannelOption.TCP_NODELAY);

View on GitHub (pinned to fb308bd8c3)

Solutions

1. List valid interface names with 'ip link' (or NetworkInterface.getNetworkInterfaces()) and set options.setMulticastNetworkInterface() to an existing one
2. Remove the setMulticastNetworkInterface call entirely and let the OS pick the default interface if multicast binding to a specific NIC is not required
3. Make the interface name configurable per environment (config/env var) and resolve it at startup
4. Ensure the named interface is up (ip link set <name> up) before creating the socket

Example fix

// before
options.setMulticastNetworkInterface("eth0");
// after
String ifName = System.getenv("MULTICAST_IF"); // e.g. resolved per host
if (ifName != null && java.net.NetworkInterface.getByName(ifName) != null) {
  options.setMulticastNetworkInterface(ifName);
}

String ifName = options.getMulticastNetworkInterface();
if (ifName != null && java.net.NetworkInterface.getByName(ifName) == null) {
  throw new IllegalStateException("Network interface not found: " + ifName
      + ". Available: " + java.net.NetworkInterface.getNetworkInterfaces());
}

When it happens

Trigger: Creating a DatagramSocket (or anything using DatagramSocketImpl) with DatagramSocketOptions.setMulticastNetworkInterface(name) set to a name that does not exist on the host, e.g. 'eth9', a VPN/tunnel interface that is down, or a Docker bridge removed since config was written.

Common situations: Hardcoded interface names from one machine deployed to another; container/Kubernetes environments where interface names differ (eth0 vs ens5); interfaces renamed by netplan/udev; VPN or multicast-capable interface being down at startup.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• eventLoopPoolSize must be > 0
• workerPoolSize must be > 0
• 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/f1894062317e670c. Report an issue: GitHub.