TooTallNate/Java-WebSocket · error · IllegalArgumentException

buffer size < 0

Error message

buffer size < 0

What it means

setReceiveBufferSize() validates its argument before storing it on AbstractWebSocket. A negative value is never a legal socket receive-buffer size, so the library throws IllegalArgumentException immediately rather than letting the value propagate to Socket.setReceiveBufferSize().

Solutions

1. Pass a positive receiveBufferSize (e.g. >= 8192 bytes) or 0 to leave the OS default
2. Fix the config parsing so sentinel values like -1 are treated as 'use default' and the setter is not called
3. Validate/clamp the value before calling: if (size >= 0) ws.setReceiveBufferSize(size);

Example fix

// before
int size = Integer.parseInt(cfg.get("recvBuf")); // "-1"
websocket.setReceiveBufferSize(size); // throws
// after
int size = Integer.parseInt(cfg.get("recvBuf"));
if (size >= 0) {
  websocket.setReceiveBufferSize(size);
}

if (size < 0) throw new IllegalArgumentException("receiveBufferSize must be >= 0, got " + size);
websocket.setReceiveBufferSize(size);

try { ws.setReceiveBufferSize(size); } catch (IllegalArgumentException e) { log.warn("Invalid buffer size, using default", e); }

When it happens

Trigger: Calling WebSocketAdapter/AbstractWebSocket.setReceiveBufferSize() with a negative int, typically from unparsed or miscomputed configuration (e.g. Integer.parseInt of '-1', a sentinel value, or an underflow in a size calculation).

Common situations: Config files or env vars where the buffer size is negative or a placeholder like -1 meaning 'unset' was passed through instead of skipping the call.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• Only Opcode.BINARY or Opcode.TEXT are allowed
• unknown role
• Payload limit reached.
• parameter must not be null
• Invalid SSL status:

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

Appendix: source

Thrown at src/main/java/org/java_websocket/AbstractWebSocket.java:371

   * Returns the TCP receive buffer size that will be used for sockets (or zero, if not explicitly set).
   * @see java.net.Socket#setReceiveBufferSize(int)
   *
   * @since 1.5.7
   */
  public int getReceiveBufferSize() {
    return receiveBufferSize;
  }

  /**
   * Sets the TCP receive buffer size that will be used for sockets.
   * If this is not explicitly set (or set to zero), the system default is used.
   * @see java.net.Socket#setReceiveBufferSize(int)
   *
   * @since 1.5.7
   */
  public void setReceiveBufferSize(int receiveBufferSize) {
    if (receiveBufferSize < 0) {
      throw new IllegalArgumentException("buffer size < 0");
    }
    this.receiveBufferSize = receiveBufferSize;
  }

}

View on GitHub (pinned to afeacbf8c0)