apache/hadoop · error · IllegalArgumentException

Illegal argument for connect()

Error message

Illegal argument for connect()

What it means

IllegalArgumentException('Illegal argument for connect()') from NetUtils.connect — a pure argument sanity check before any network activity: socket is null, endpoint (SocketAddress) is null, or timeout is negative. It is a guard against programming/config errors rather than a network condition; the actual connection attempt happens after this check and reports real failures as IOExceptions.

Source

Thrown at hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/net/NetUtils.java:594

    connect(socket, address, null, timeout);
  }

  /**
   * Like {@link NetUtils#connect(Socket, SocketAddress, int)} but
   * also takes a local address and port to bind the socket to. 
   * 
   * @param socket socket.
   * @param endpoint the remote address
   * @param localAddr the local address to bind the socket to
   * @param timeout timeout in milliseconds
   * @throws IOException raised on errors performing I/O.
   */
  public static void connect(Socket socket, 
                             SocketAddress endpoint,
                             SocketAddress localAddr,
                             int timeout) throws IOException {
    if (socket == null || endpoint == null || timeout < 0) {
      throw new IllegalArgumentException("Illegal argument for connect()");
    }
    
    SocketChannel ch = socket.getChannel();
    
    if (localAddr != null) {
      Class localClass = localAddr.getClass();
      Class remoteClass = endpoint.getClass();
      Preconditions.checkArgument(localClass.equals(remoteClass),
          "Local address %s must be of same family as remote address %s.",
          localAddr, endpoint);
      socket.bind(localAddr);
    }

    try {
      if (ch == null) {
        // let the default implementation handle it.
        socket.connect(endpoint, timeout);
      } else {

View on GitHub (pinned to 2add963021)

Solutions

1. Check for null socket/endpoint and non-negative timeout before calling connect
2. Trace where the null endpoint came from — usually an unset configuration property; set it or fail with a clearer message
3. Use 0 for an infinite/system timeout instead of negative values

Example fix

// before
NetUtils.connect(sock, null, 0); // null endpoint -> IllegalArgumentException

// after
Preconditions.checkNotNull(endpoint, "endpoint is null (check the address config)");
Preconditions.checkArgument(timeout >= 0, "timeout must be >= 0, got %s", timeout);
NetUtils.connect(sock, endpoint, timeout);

Objects.requireNonNull(socket, "socket");
Objects.requireNonNull(endpoint, "endpoint");
if (timeout < 0) throw new IllegalArgumentException("timeout >= 0 required, got " + timeout);

When it happens

Trigger: Passing a null endpoint obtained from an unset address property or a failed lookup; computing timeout from configuration where a negative default (-1) leaks through; calling connect with a socket variable that was never initialized.

Common situations: Code paths where the endpoint came from NetUtils.createSocketAddr on a missing config; retry loops that null out the socket/endpoint between iterations; a timeout constant configured as -1 meaning 'infinite' passed to an API that requires >= 0.

Related errors

• Localhost targeted connection resulted in a loopback. No dae
• Invalid read parameters: buf.length=%d, off=%d, len=%d
• Move destination must be different from source for %s.
• offset: %s is out of range [%s, %s]
• Bad format: {}

AI-assisted analysis of apache/hadoop@2add963021 (2026-08-22). Data as JSON: /api/errors/e9559abb6931a764. Report an issue: GitHub.