TooTallNate/Java-WebSocket · error · InvalidHandshakeException

Handshake data rejected by client.

Error message

Handshake data rejected by client.

What it means

In startHandshake (client role), the library first calls wsl.onWebsocketHandshakeSentAsClient(); if the application's listener throws InvalidDataException, the library converts it into InvalidHandshakeException('Handshake data rejected by client.') and aborts the WebSocket opening handshake. It means your own handshake-verification callback rejected the outgoing request.

Solutions

1. Inspect your onWebsocketHandshakeSentAsClient implementation — remove or fix the InvalidDataException it throws.
2. Ensure required handshake headers/tokens are set before connect().
3. If rejection is intended, handle InvalidHandshakeException from connect()/onOpen failure gracefully.
4. If you need error detail, log inside the callback before throwing.

Example fix

// before
@Override
public void onWebsocketHandshakeSentAsClient(WebSocket conn, ClientHandshake request) throws InvalidDataException {
  throw new InvalidDataException(1006, "no token");
}
// after
@Override
public void onWebsocketHandshakeSentAsClient(WebSocket conn, ClientHandshake request) throws InvalidDataException {
  // validate or accept; only throw when genuinely invalid
}

// validate handshake inputs before connecting
if (authToken == null) throw new IllegalStateException("token must be set before connect()");

try { client.connectBlocking(); } catch (InvalidHandshakeException e) {
  log.error("handshake rejected: " + e.getMessage());
}

When it happens

Trigger: Implementing onWebsocketHandshakeSentAsClient in a WebSocketClient subclass and throwing InvalidDataException from it (e.g. rejecting missing headers), then connecting.

Common situations: Custom header validation/authorization checks in the handshake callback; strict verification of the handshake request that fails because a required header or token is absent.

Understand the failure class

• SSL/TLS and certificate errors — how TLS handshakes and certificate validation fail.

Related errors

• rejected because of
• connection closed unexpectedly by peer
• Invalid status code received
• unknown role
• missing Sec-WebSocket-Key

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

Appendix: source

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

  @Override
  public boolean hasBufferedData() {
    return !this.outQueue.isEmpty();
  }

  public void startHandshake(ClientHandshakeBuilder handshakedata)
      throws InvalidHandshakeException {
    // Store the Handshake Request we are about to send
    this.handshakerequest = draft.postProcessHandshakeRequestAsClient(handshakedata);

    resourceDescriptor = handshakedata.getResourceDescriptor();
    assert (resourceDescriptor != null);

    // Notify Listener
    try {
      wsl.onWebsocketHandshakeSentAsClient(this, this.handshakerequest);
    } catch (InvalidDataException e) {
      // Stop if the client code throws an exception
      throw new InvalidHandshakeException("Handshake data rejected by client.");
    } catch (RuntimeException e) {
      log.error("Exception in startHandshake", e);
      wsl.onWebsocketError(this, e);
      throw new InvalidHandshakeException("rejected because of " + e);
    }

    // Send
    write(draft.createHandshake(this.handshakerequest));
  }

  private void write(ByteBuffer buf) {
    log.trace("write({}): {}", buf.remaining(),
        buf.remaining() > 1000 ? "too big to display" : new String(buf.array()));

    outQueue.add(buf);
    wsl.onWriteDemand(this);
  }

View on GitHub (pinned to afeacbf8c0)