TooTallNate/Java-WebSocket · error · IllegalStateException

You cannot initialize a reconnect out of the websocket…

Error message

You cannot initialize a reconnect out of the websocket thread. Use reconnect in another thread to ensure a successful cleanup.

What it means

Guard in WebSocketClient.reset(): reconnect/reconnectBlocking call reset(), which interrupts and joins the write and connect-read threads. If invoked from the websocket's own writeThread or connectReadThread, joining itself would deadlock, so the call is rejected. This is a caller-context check, not a data validation error.

Solutions

1. Call reconnect() or reconnectBlocking() from your own application thread, never from onMessage/onError/onClose or other websocket-thread callbacks.
2. Schedule the reconnect on a separate executor/thread, e.g. `new Thread(client::reconnect).start()`.
3. Use a scheduler (ScheduledExecutorService) with a delay to reconnect after the callback returns.

When it happens

Trigger: Thrown at src/main/java/org/java_websocket/client/WebSocketClient.java:353 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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

Appendix: source

Thrown at src/main/java/org/java_websocket/client/WebSocketClient.java:353

   * @param timeUnit The timeout time unit
   * @return Returns whether it succeeded or not.
   * @throws InterruptedException Thrown when the threads get interrupted
   * @since 1.6.1
   */
  public boolean reconnectBlocking(long timeout, TimeUnit timeUnit) throws InterruptedException {
    reset();
    return connectBlocking(timeout, timeUnit);
  }

  /**
   * Reset everything relevant to allow a reconnect
   *
   * @since 1.3.8
   */
  private void reset() {
    Thread current = Thread.currentThread();
    if (current == writeThread || current == connectReadThread) {
      throw new IllegalStateException(
          "You cannot initialize a reconnect out of the websocket thread. Use reconnect in another thread to ensure a successful cleanup.");
    }
    try {
      // This socket null check ensures we can reconnect a socket that failed to connect. It's an uncommon edge case, but we want to make sure we support it
      if (engine.getReadyState() == ReadyState.NOT_YET_CONNECTED && socket != null) {
        // Closing the socket when we have not connected prevents the writeThread from hanging on a write indefinitely during connection teardown
        socket.close();
      }
      closeBlocking();

      if (writeThread != null) {
        this.writeThread.interrupt();
        this.writeThread.join();
        this.writeThread = null;
      }
      if (connectReadThread != null) {
        this.connectReadThread.interrupt();
        this.connectReadThread.join();

View on GitHub (pinned to afeacbf8c0)