TooTallNate/Java-WebSocket · error · InvalidHandshakeException

rejected because of

Error message

rejected because of 

What it means

Also in startHandshake: when the application's onWebsocketHandshakeSentAsClient callback throws an uncaught RuntimeException, the library logs it, notifies onWebsocketError, and rethrows it as InvalidHandshakeException with the message 'rejected because of ' + the exception. The suffix contains the original RuntimeException's toString.

Solutions

1. Read the chained exception ('rejected because of java.lang.NullPointer...') to find the real cause.
2. Wrap risky logic inside onWebsocketHandshakeSentAsClient in try/catch or fix the underlying bug.
3. Avoid performing side-effectful or fallible operations in the handshake callback.
4. Catch InvalidHandshakeException around connect() and surface the cause to logs.

Example fix

// before
public void onWebsocketHandshakeSentAsClient(WebSocket conn, ClientHandshake req) {
  String token = config.auth.token.toUpperCase(); // NPE if token null
}
// after
public void onWebsocketHandshakeSentAsClient(WebSocket conn, ClientHandshake req) {
  String token = config.auth != null && config.auth.token != null ? config.auth.token.toUpperCase() : null;
}

// guard callback inputs
Objects.requireNonNull(config, "config");

try { client.connectBlocking(); } catch (InvalidHandshakeException e) {
  // message starts with 'rejected because of' — inspect the chained RuntimeException cause
  log.error("client code crashed during handshake", e.getCause());
}

When it happens

Trigger: Any RuntimeException escaping your onWebsocketHandshakeSentAsClient implementation (NPE while reading a config field, ClassCastException on a header value, etc.) during client connect.

Common situations: Null pointer in custom handshake code accessing uninitialized members; bugs in header manipulation; exceptions from third-party code invoked inside the callback.

Related errors

• Handshake data rejected by client.
• 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/13f5e3bbc8369004. Report an issue: GitHub.

Appendix: source

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

  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);
  }

  /**
   * Write a list of bytebuffer (frames in binary form) into the outgoing queue
   *
   * @param bufs the list of bytebuffer

View on GitHub (pinned to afeacbf8c0)