TooTallNate/Java-WebSocket · error · IllegalArgumentException

parameters must not be null

Error message

parameters must not be null

What it means

The WebSocketImpl constructor throws IllegalArgumentException when the WebSocketListener is null, or when both the Draft is null and the role is SERVER — a server-side socket cannot negotiate without a draft. It is a fail-fast guard because the object is unusable without a listener.

Solutions

1. Always pass a valid WebSocketListener (usually the WebSocketServer/WebSocketClient instance).
2. Pass a concrete Draft (e.g. new Draft_6455()) when constructing server-role instances.
3. If you control the code, check listener/draft for null before invoking the constructor.

Example fix

// before
WebSocketImpl ws = new WebSocketImpl(null, null);
// after
WebSocketImpl ws = new WebSocketImpl(this, new Draft_6455());

if (listener == null || (role == Role.SERVER && draft == null)) {
  throw new IllegalArgumentException("listener required; draft required for server role");
}

try { new WebSocketImpl(listener, draft); } catch (IllegalArgumentException e) { log.error("bad websocket args", e); }

When it happens

Trigger: Passing null as the WebSocketListener to new WebSocketImpl(listener, draft), or constructing a server-role WebSocketImpl with draft == null.

Common situations: Custom WebSocketServer implementations subclassing WebSocketImpl and passing a wrong/uninitialized listener reference (e.g. 'this' before initialization); reflection-based instantiation with missing arguments.

Related errors

• parameter must not be null
• parameter must not be null
• Cannot send 'null' data to a WebSocketImpl.
• buffer size < 0
• onPreparePing(WebSocket) returned null. PingFrame to sent…

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

Appendix: source

Thrown at src/main/java/org/java_websocket/WebSocketImpl.java:204

    // draft.copyInstance will be called when the draft is first needed
    if (drafts == null || drafts.isEmpty()) {
      knownDrafts = new ArrayList<>();
      knownDrafts.add(new Draft_6455());
    } else {
      knownDrafts = drafts;
    }
  }

  /**
   * creates a websocket with client role
   *
   * @param listener The listener for this instance
   * @param draft    The draft which should be used
   */
  public WebSocketImpl(WebSocketListener listener, Draft draft) {
    // socket can be null because we want do be able to create the object without already having a bound channel
    if (listener == null || (draft == null && role == Role.SERVER)) {
      throw new IllegalArgumentException("parameters must not be null");
    }
    this.outQueue = new LinkedBlockingQueue<>();
    inQueue = new LinkedBlockingQueue<>();
    this.wsl = listener;
    this.role = Role.CLIENT;
    if (draft != null) {
      this.draft = draft.copyInstance();
    }
  }

  /**
   * Method to decode the provided ByteBuffer
   *
   * @param socketBuffer the ByteBuffer to decode
   */
  public void decode(ByteBuffer socketBuffer) {
    assert (socketBuffer.hasRemaining());
    if (log.isTraceEnabled()) {

View on GitHub (pinned to afeacbf8c0)