TooTallNate/Java-WebSocket · error · IllegalArgumentException

Could not get address of channel passed to WebSocketServer…

Error message

Could not get address of channel passed to WebSocketServer, make sure it is bound

What it means

WebSocketServer's constructor can accept an existing, already-bound ServerSocketChannel. checkAddressOfExistingChannel() retrieves the channel's local address to know the bind address; if getLocalAddress() throws IOException or returns null (channel open but not bound), it throws IllegalArgumentException telling you the channel must be bound.

Solutions

1. Bind the channel before constructing WebSocketServer: channel.bind(new InetSocketAddress(port))
2. Verify channel.getLocalAddress() returns a non-null address before passing the channel in
3. Ensure nothing unbinds/closes the channel between binding and server construction
4. If you don't need an existing channel, use the WebSocketServer(address) constructors that bind internally

Example fix

// before
ServerSocketChannel ch = ServerSocketChannel.open();
WebSocketServer server = new MyServer(new InetSocketAddress(8887), Collections.singletonList(ch));
// after
ServerSocketChannel ch = ServerSocketChannel.open();
ch.bind(new InetSocketAddress(8887));
WebSocketServer server = new MyServer(new InetSocketAddress(8887), Collections.singletonList(ch));

assert channel.isOpen();
if (channel.getLocalAddress() == null) {
  throw new IllegalStateException("ServerSocketChannel must be bound before passing to WebSocketServer");
}

boolean isBound(ServerSocketChannel ch) throws IOException {
  return ch != null && ch.isOpen() && ch.getLocalAddress() != null;
}

try {
  WebSocketServer server = new MyServer(addr, Collections.singletonList(channel));
} catch (IllegalArgumentException e) {
  // channel unbound: bind it or construct WebSocketServer from an address instead
}

When it happens

Trigger: Passing a ServerSocketChannel to the WebSocketServer constructor that was opened but never bound (socketChannel.bind(...)), or whose bind failed / was closed after opening.

Common situations: Advanced setups sharing a pre-bound channel with other code, where the bind call was skipped, failed silently, or happened after constructing the server.

Related errors

• buffer size < 0
• parameter must not be null
• Invalid SSL status:
• Buffer underflow occurred after a wrap. I don't think we…
• parameter must not be null

AI-assisted analysis of TooTallNate/Java-WebSocket@afeacbf8c0 (2026-09-09). Data as JSON: /api/errors/9a810f8a1da37b51. Report an issue: GitHub.

Appendix: source

Thrown at src/main/java/org/java_websocket/server/WebSocketServer.java:191

   * @param address      The address (host:port) this server should listen on.
   * @param decodercount The number of {@link WebSocketWorker}s that will be used to process the
   *                     incoming network data. By default this will be <code>Runtime.getRuntime().availableProcessors()</code>
   * @param drafts       The versions of the WebSocket protocol that this server instance should
   *                     comply to. Clients that use an other protocol version will be rejected.
   * @see #WebSocketServer(InetSocketAddress, int, List, Collection) more details here
   */
  public WebSocketServer(InetSocketAddress address, int decodercount, List<Draft> drafts) {
    this(address, decodercount, drafts, new HashSet<WebSocket>());
  }

  // Small internal helper function to get around limitations of Java constructors.
  private static InetSocketAddress checkAddressOfExistingChannel(ServerSocketChannel existingChannel) {
    assert existingChannel.isOpen();
    SocketAddress addr;
    try {
      addr = existingChannel.getLocalAddress();
    } catch (IOException e) {
      throw new IllegalArgumentException("Could not get address of channel passed to WebSocketServer, make sure it is bound", e);
    }
    if (addr == null) {
      throw new IllegalArgumentException("Could not get address of channel passed to WebSocketServer, make sure it is bound");
    }
    return (InetSocketAddress)addr;
  }

  /**
   * @param existingChannel An already open and bound server socket channel, which this server will use.
   * For example, it can be System.inheritedChannel() to implement socket activation.
   */
  public WebSocketServer(ServerSocketChannel existingChannel) {
    this(checkAddressOfExistingChannel(existingChannel));
    this.server = existingChannel;
  }

  /**
   * Creates a WebSocketServer that will attempt to bind/listen on the given <var>address</var>, and

View on GitHub (pinned to afeacbf8c0)