TooTallNate/Java-WebSocket · error · InvalidHandshakeException

not an http header

Error message

not an http header

What it means

This is a format validation inside Draft.translateHandshakeHttp while parsing the HTTP handshake headers. Each header line must be a 'Name: value' pair; a line that does not split into exactly two parts on ':' is not a valid HTTP header, and the library aborts the whole handshake with InvalidHandshakeException rather than guessing. The faulty input is a malformed header line (missing colon, empty name, or corrupt line) in the WebSocket opening-handshake data received from the remote peer.

Solutions

1. Inspect the raw handshake bytes/lines sent by the peer and fix any header missing a colon separator
2. Ensure the peer is a compliant WebSocket/HTTP endpoint producing well-formed 'Header: value' lines
3. Check for proxies or intermediaries mangling or injecting non-header lines into the handshake response
4. On the server side, validate client handshake headers before sending; on the client side, verify the server URL points to a real WebSocket endpoint

When it happens

Trigger: Thrown at src/main/java/org/java_websocket/drafts/Draft.java:117 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/4de05d4b50e008b8. Report an issue: GitHub.

Appendix: source

Thrown at src/main/java/org/java_websocket/drafts/Draft.java:117

    String line = readStringLine(buf);
    if (line == null) {
      throw new IncompleteHandshakeException(buf.capacity() + 128);
    }

    String[] firstLineTokens = line.split(" ", 3);// eg. HTTP/1.1 101 Switching the Protocols
    if (firstLineTokens.length != 3) {
      throw new InvalidHandshakeException();
    }
    if (role == Role.CLIENT) {
      handshake = translateHandshakeHttpClient(firstLineTokens, line);
    } else {
      handshake = translateHandshakeHttpServer(firstLineTokens, line);
    }
    line = readStringLine(buf);
    while (line != null && line.length() > 0) {
      String[] pair = line.split(":", 2);
      if (pair.length != 2) {
        throw new InvalidHandshakeException("not an http header");
      }
      // If the handshake contains already a specific key, append the new value
      if (handshake.hasFieldValue(pair[0])) {
        handshake.put(pair[0],
            handshake.getFieldValue(pair[0]) + "; " + pair[1].replaceFirst("^ +", ""));
      } else {
        handshake.put(pair[0], pair[1].replaceFirst("^ +", ""));
      }
      line = readStringLine(buf);
    }
    if (line == null) {
      throw new IncompleteHandshakeException();
    }
    return handshake;
  }

  /**
   * Checking the handshake for the role as server

View on GitHub (pinned to afeacbf8c0)