TooTallNate/Java-WebSocket · error · IllegalStateException

this method must be used in conjunction with flushAndClose

Error message

this method must be used in conjunction with flushAndClose

What it means

The no-argument closeConnection() can only be called after flushAndClose() has recorded the close code, message, and remote flag (closedremotely). Calling it standalone means the close parameters were never set, so the library throws IllegalStateException to prevent closing without a defined close handshake outcome.

Solutions

1. Use close(int code, String message) or closeConnection(int code, String message, boolean remote) instead of the parameterless closeConnection().
2. If you intentionally want flush-then-close, call flushAndClose(code, message, remote) first, then closeConnection().
3. For a normal graceful close just call websocket.close().

Example fix

// before
conn.closeConnection();
// after
conn.close(1000, "normal closure");

// prefer explicit close parameters
code = 1000; message = "normal closure";

When it happens

Trigger: Calling websocket.closeConnection() (the parameterless overload) without first calling flushAndClose(code, message, remote) on the same connection.

Common situations: Server-side code that wants to forcibly close after flushing but calls closeConnection() instead of close(code, message); custom server implementations mixing the two close APIs.

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

• can only be started once.
• Invalid SSL status:
• Cannot call setDaemon after server is already started!

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

Appendix: source

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

      this.wsl.onWebsocketClose(this, code, message, remote);
    } catch (RuntimeException e) {

      wsl.onWebsocketError(this, e);
    }
    if (draft != null) {
      draft.reset();
    }
    handshakerequest = null;
    readyState = ReadyState.CLOSED;
  }

  protected void closeConnection(int code, boolean remote) {
    closeConnection(code, "", remote);
  }

  public void closeConnection() {
    if (closedremotely == null) {
      throw new IllegalStateException("this method must be used in conjunction with flushAndClose");
    }
    closeConnection(closecode, closemessage, closedremotely);
  }

  public void closeConnection(int code, String message) {
    closeConnection(code, message, false);
  }

  public synchronized void flushAndClose(int code, String message, boolean remote) {
    if (flushandclosestate) {
      return;
    }
    closecode = code;
    closemessage = message;
    closedremotely = remote;

    flushandclosestate = true;

View on GitHub (pinned to afeacbf8c0)