TooTallNate/Java-WebSocket · error · IllegalArgumentException

Don't know how to handle

Error message

Don't know how to handle {opcode}

What it means

Draft_6455's opcode-to-numeric mapping throws IllegalArgumentException("Don't know how to handle <opcode>") when converting an Opcode enum value that has no numeric mapping (valid values are 0-10). This happens only with an internal/unknown Opcode, typically CONTINUOUS-with-FIN edge usage or a future opcode not covered by the if-chain.

Solutions

1. Only send frames using the draft's createFrames API instead of hand-building Framedata with raw opcodes
2. Upgrade Java-WebSocket so Opcode enum and Draft_6455 mapping are from the same version
3. Audit custom subclasses/frames that inject unusual opcodes into the send path
4. Catch IllegalArgumentException at the send boundary and log the offending opcode

Example fix

// before: hand-built frame with unmapped opcode
FrameData f = new CustomFrame(someOpcode, payload);
webSocket.sendFrame(f);
// after
List<Framedata> frames = draft.createFrames(payloadBytes, true);
webSocket.sendFrame(frames.get(0));

// only send frames produced by the draft's own API
List<Framedata> frames = draft.createFrames(payload, true); // never hand-build opcodes

try {
  webSocket.sendFrame(frame);
} catch (IllegalArgumentException e) {
  log.error("Unsupported opcode for this draft: {}", e.getMessage());
}

When it happens

Trigger: Calling the private numeric conversion (used when building outgoing frame headers) with an Opcode outside CONTINUOUS(0), TEXT(1), BINARY(2), CLOSE(8), PING(9), PONG(10) — e.g. a custom or newer Opcode enum member.

Common situations: Library version mismatch where custom code constructs frames with an Opcode the 6455 draft mapping does not know; passing frame objects built by another draft implementation; internal bugs.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Unknown opcode
• buffer size < 0
• parameter must not be null
• Invalid SSL status:
• Buffer underflow occurred after a wrap. I don't think we…

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

Appendix: source

Thrown at src/main/java/org/java_websocket/drafts/Draft_6455.java:868

    return buffer;
  }


  private byte fromOpcode(Opcode opcode) {
    if (opcode == Opcode.CONTINUOUS) {
      return 0;
    } else if (opcode == Opcode.TEXT) {
      return 1;
    } else if (opcode == Opcode.BINARY) {
      return 2;
    } else if (opcode == Opcode.CLOSING) {
      return 8;
    } else if (opcode == Opcode.PING) {
      return 9;
    } else if (opcode == Opcode.PONG) {
      return 10;
    }
    throw new IllegalArgumentException("Don't know how to handle " + opcode.toString());
  }

  private Opcode toOpcode(byte opcode) throws InvalidFrameException {
    switch (opcode) {
      case 0:
        return Opcode.CONTINUOUS;
      case 1:
        return Opcode.TEXT;
      case 2:
        return Opcode.BINARY;
      // 3-7 are not yet defined
      case 8:
        return Opcode.CLOSING;
      case 9:
        return Opcode.PING;
      case 10:
        return Opcode.PONG;
      // 11-15 are not yet defined

View on GitHub (pinned to afeacbf8c0)