apache/hadoop · error · IOException

Channel is null. Check how the channel or socket is created.

Error message

Channel is null. Check how the channel or socket is created.

What it means

SocketIOWithTimeout implements read/write/connect timeouts on top of java.nio select, so it requires a real channel. checkChannelValidity throws IOException when the channel is null — the dominant cause is a classic java.net.Socket (created via new Socket()) whose getChannel() returns null because it was never associated with a channel. The code deliberately uses IOException, not a RuntimeException, because this is a common setup mismatch.

Source

Thrown at hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/net/SocketIOWithTimeout.java:91

    return !closed && channel.isOpen();
  }

  SelectableChannel getChannel() {
    return channel;
  }
  
  /** 
   * Utility function to check if channel is ok.
   * Mainly to throw IOException instead of runtime exception
   * in case of mismatch. This mismatch can occur for many runtime
   * reasons.
   */
  static void checkChannelValidity(Object channel) throws IOException {
    if (channel == null) {
      /* Most common reason is that original socket does not have a channel.
       * So making this an IOException rather than a RuntimeException.
       */
      throw new IOException("Channel is null. Check " +
                            "how the channel or socket is created.");
    }
    
    if (!(channel instanceof SelectableChannel)) {
      throw new IOException("Channel should be a SelectableChannel");
    }    
  }
  
  /**
   * Performs actual IO operations. This is not expected to block.
   *  
   * @param buf
   * @return number of bytes (or some equivalent). 0 implies underlying
   *         channel is drained completely. We will wait if more IO is 
   *         required.
   * @throws IOException
   */
  abstract int performIO(ByteBuffer buf) throws IOException;  

View on GitHub (pinned to 2add963021)

Solutions

1. Create the connection with SocketChannel.open() (or accept via ServerSocketChannel) so getChannel() is non-null
2. For plain sockets, use their ordinary blocking InputStream/OutputStream with SO_TIMEOUT instead of the channel-based wrappers
3. If you must inject sockets, check socket.getChannel() != null before building the stream wrappers

Example fix

// before
Socket s = new Socket(host, port);
SocketInputStream in = new SocketInputStream(s.getChannel(), timeout); // channel == null -> IOException

// after
SocketChannel ch = SocketChannel.open(new InetSocketAddress(host, port));
SocketInputStream in = new SocketInputStream(ch, timeout);

SocketChannel ch = socket.getChannel();
if (ch == null) {
  // fall back to blocking streams with SO_TIMEOUT
  socket.setSoTimeout((int) timeoutMs);
  return socket.getInputStream();
}
return new SocketInputStream(ch, timeoutMs);

static boolean hasChannel(Socket s) {
  return s != null && s.getChannel() != null;
}

catch (IOException e) {
  if (e.getMessage().contains("Channel is null")) {
    // recreate the connection via SocketChannel.open() and retry once
  }
}

When it happens

Trigger: Constructing SocketInputStream/SocketOutputStream (subclasses of SocketIOWithTimeout) around a plain Socket: socket.getChannel() == null, so the wrapper cannot multiplex and throws immediately.

Common situations: Wrapping sockets from new Socket(host, port) or plain ServerSocket.accept() instead of SocketChannel.open()/ServerSocketChannel; custom SocketFactory implementations returning channel-less sockets; code assuming every Socket has a channel.

Related errors

• Channel should be a SelectableChannel
• Buffer has no data left.
• {} millis timeout while waiting for channel to be ready for
• Interrupted while waiting for IO on channel {}. Total timeou
• getXAttrs on path `{}' is not within a mount point

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