redis/jedis · error · IllegalArgumentException

Unknown protocol

Error message

Unknown protocol 

What it means

getRedisProtocol(URI) reads a `protocol=` query parameter and matches its value against the known RedisProtocol enum versions. If the parameter value doesn't equal any enum's version string, the library throws IllegalArgumentException("Unknown protocol ..."). Missing parameter returns null (default).

Solutions

1. Use the exact version string matching RedisProtocol.values()[i].version(), e.g. `?protocol=3` for RESP3.
2. Print the valid values from RedisProtocol.values() to see accepted strings before crafting the URI.
3. Drop the protocol parameter entirely if you want the default (RESP2) and configure the protocol programmatically via RedisProtocol in the client config instead.

Example fix

// before
URI uri = URI.create("redis://localhost:6379/?protocol=resp3"); // throws
// after
URI uri = URI.create("redis://localhost:6379/?protocol=3");

static boolean hasKnownProtocol(URI uri) {
  String q = uri.getQuery();
  if (q == null) return true;
  for (String p : q.split("&")) {
    if (p.startsWith("protocol=")) {
      String v = p.substring("protocol=".length());
      for (RedisProtocol rp : RedisProtocol.values()) {
        if (rp.version().equals(v)) return true;
      }
      return false;
    }
  }
  return true;
}

try {
  RedisProtocol p = JedisURIHelper.getRedisProtocol(uri);
} catch (IllegalArgumentException e) {
  // fall back to default protocol (null)
}

When it happens

Trigger: A URI whose query string contains protocol=<value> where <value> is not a valid RedisProtocol version, e.g. `redis://host:6379/?protocol=3` or `?protocol=resp2` when only values like `2`/`3` matching RedisProtocol.version() are accepted.

Common situations: Guessing the parameter format (name-based 'resp3' vs version-based); copying URIs from other clients (e.g. node-redis uses different protocol syntax); typos or whitespace in the query value.

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

• Buffer size <= 0
• Cannot open Redis connection due invalid URI
• Unknown message type
• Unknown message type:
• Unknown endpoint type:

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

Appendix: source

Thrown at src/main/java/redis/clients/jedis/util/JedisURIHelper.java:144

   *
   * @param uri
   * @return Redis protocol, or null if not specified
   */
  public static RedisProtocol getRedisProtocol(URI uri) {
    if (uri.getQuery() == null) return null;

    String[] params = uri.getQuery().split("&");
    for (String param : params) {
      int idx = param.indexOf("=");
      if (idx < 0) continue;
      if ("protocol".equals(param.substring(0, idx))) {
        String ver = param.substring(idx + 1);
        for (RedisProtocol proto : RedisProtocol.values()) {
          if (proto.version().equals(ver)) {
            return proto;
          }
        }
        throw new IllegalArgumentException("Unknown protocol " + ver);
      }
    }
    return null; // null (default) when not defined
  }

  /**
   * Validates that the given URI is a valid Redis URI.
   * <p>
   * A valid Redis URI must:
   * <ul>
   *   <li>Have a scheme of "redis" or "rediss" (case-insensitive)</li>
   *   <li>Have a non-empty host</li>
   *   <li>Have a valid port defined</li>
   * </ul>
   * <p>
   *
   * @param uri the URI to validate
   * @return true if the URI is valid for Redis connections, false otherwise

View on GitHub (pinned to 6dac31d4c2)