TooTallNate/Java-WebSocket · error · IllegalArgumentException

address and connectionscontainer must not be null and you…

Error message

address and connectionscontainer must not be null and you need at least 1 decoder

What it means

Constructor validation in WebSocketServer(InetSocketAddress, int, List<Draft>, Collection<WebSocket>): the bind address and the connections container must be non-null and the decoder count must be at least 1. The decoder workers are created eagerly in the constructor, so zero decoders would make the server unable to process incoming frames.

Solutions

1. Pass a valid address: new InetSocketAddress(port) or InetAddress.getByName(host) with a port.
2. Pass a live, mutable collection for connectionscontainer, e.g. new ConcurrentHashMap().keySet() or new CopyOnWriteArraySet<>().
3. Use decodercount >= 1, typically a small positive number sized to expected load.
4. Prefer the simpler WebSocketServer(InetSocketAddress) constructor and configure threads/drafts via setters if you do not need the full 4-arg form.

Example fix

// before
WebSocketServer server = new WebSocketServer(null, 0, drafts, connections);
// after
WebSocketServer server = new WebSocketServer(
    new InetSocketAddress(8887), 2, drafts, new CopyOnWriteArraySet<>());

Objects.requireNonNull(address, "address must not be null");
Objects.requireNonNull(connections, "connectionscontainer must not be null");
if (decodercount < 1) throw new IllegalArgumentException("decodercount must be >= 1");

try {
  server = new WebSocketServer(address, decodercount, drafts, connections);
} catch (IllegalArgumentException e) {
  log.error("Invalid WebSocketServer arguments: {}", e.getMessage());
  server = new WebSocketServer(address != null ? address : new InetSocketAddress(8080));
}

When it happens

Trigger: Passing null as the InetSocketAddress, passing null for the connections container, or passing decodercount < 1 (e.g. 0 or a config-derived value of 0) to the 4-arg WebSocketServer constructor.

Common situations: Building the server from configuration where the listen address or port was never parsed (null slips through); tuning thread counts from properties and getting 0; refactoring that passes a null collection instead of a fresh empty collection.

Related errors

• parameter must not be null
• parameter must not be null
• 1007
• 1002
• buffer size < 0

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

Appendix: source

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

   * @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.
   * @param connectionscontainer Allows to specify a collection that will be used to store the
   *                             websockets in. <br> If you plan to often iterate through the
   *                             currently connected websockets you may want to use a collection
   *                             that does not require synchronization like a {@link
   *                             CopyOnWriteArraySet}. In that case make sure that you overload
   *                             {@link #removeConnection(WebSocket)} and {@link
   *                             #addConnection(WebSocket)}.<br> By default a {@link HashSet} will
   *                             be used.
   * @see #removeConnection(WebSocket) for more control over syncronized operation
   * @see <a href="https://github.com/TooTallNate/Java-WebSocket/wiki/Drafts" > more about
   * drafts</a>
   */
  public WebSocketServer(InetSocketAddress address, int decodercount, List<Draft> drafts,
      Collection<WebSocket> connectionscontainer) {
    if (address == null || decodercount < 1 || connectionscontainer == null) {
      throw new IllegalArgumentException(
          "address and connectionscontainer must not be null and you need at least 1 decoder");
    }

    if (drafts == null) {
      this.drafts = Collections.emptyList();
    } else {
      this.drafts = drafts;
    }

    this.address = address;
    this.connections = connectionscontainer;
    setTcpNoDelay(false);
    setReuseAddr(false);
    iqueue = new LinkedList<>();

    decoders = new ArrayList<>(decodercount);
    buffers = new LinkedBlockingQueue<>();
    for (int i = 0; i < decodercount; i++) {

View on GitHub (pinned to afeacbf8c0)