redis/jedis · error · IllegalArgumentException

Unknown protocol version:

Error message

Unknown protocol version: 

What it means

RedisProtocol.from(Long) maps the HELLO reply's protocol version number to the RESP2/RESP3 enum. Only 2 and 3 are recognized; any other numeric value throws IllegalArgumentException with 'Unknown protocol version: N'. This happens when the server reports a protocol version the client does not support.

Solutions

1. Upgrade jedis to a version that recognizes the server's protocol version.
2. Configure the server (or connection protocol option) to use RESP2 or RESP3, e.g. HELLO 2 or protocol 2.
3. Validate/normalize the proto value before calling from(), catching IllegalArgumentException to fall back to a supported protocol.

Example fix

// before
RedisProtocol proto = RedisProtocol.from(helloProto);

// after
RedisProtocol proto;
try {
  proto = RedisProtocol.from(helloProto);
} catch (IllegalArgumentException e) {
  proto = RedisProtocol.RESP2; // safe fallback
}

if (proto == null || (proto != 2 && proto != 3)) {
  proto = 2L; // default to RESP2 before mapping
}
RedisProtocol p = RedisProtocol.from(proto);

boolean isSupportedProtocol(Long proto) { return proto != null && (proto == 2 || proto == 3); }

try {
  protocol = RedisProtocol.from(serverProto);
} catch (IllegalArgumentException e) {
  protocol = RedisProtocol.RESP2;
}

When it happens

Trigger: Calling RedisProtocol.from() with a Long other than 2 or 3 — e.g. parsing a HELLO response that returned proto 4 (hypothetical future server), or passing a hand-built/mis-parsed value.

Common situations: Connecting to a newer/nonstandard Redis-compatible server advertising an unknown protocol version; proxy or middleware altering HELLO output; unit tests feeding raw protocol numbers.

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 reply:
• Unknown message type
• Unknown message type:
• Bulk reply length is less than expected
• Unsupported protocol:

AI-assisted analysis of redis/jedis@6dac31d4c2 (2026-09-08). Data as JSON: /api/errors/9c1ca77fc02c9b0a. Report an issue: GitHub.

Appendix: source

Thrown at src/main/java/redis/clients/jedis/RedisProtocol.java:48

  private RedisProtocol(String ver) {
    this.version = ver;
  }

  public String version() {
    return version;
  }

  /**
   * Returns the RedisProtocol enum value corresponding to the given protocol version number.
   * @param proto the protocol version number (2 or 3)
   * @return the corresponding RedisProtocol enum value
   * @throws JedisProtocolNotSupportedException if the protocol version is not recognized
   */
  public static RedisProtocol from(Long proto) {
    if (proto == null) return null;
    if (proto == 2) return RESP2;
    if (proto == 3) return RESP3;
    throw new IllegalArgumentException("Unknown protocol version: " + proto);
  }

  public static RedisProtocol orServerDefault(RedisProtocol proto) {
    return (proto == null) ? REDIS_SERVER_DEFAULT_PROTO : proto;
  }
}

View on GitHub (pinned to 6dac31d4c2)