redis/jedis · error · IllegalArgumentException

Client-side caching is only supported with RESP3.

Error message

Client-side caching is only supported with RESP3.

What it means

Client-side caching in Jedis maintains a local key-value cache invalidated via Redis client-tracking push messages, which are only available on the RESP3 protocol. When building a client through AbstractClientBuilder with a cache or cacheConfig configured, validateCommonConfiguration() checks whether the supplied connection config can negotiate RESP3; if it cannot, the build fails fast with this IllegalArgumentException rather than silently operating a broken cache.

Solutions

Set the protocol to RESP3 in the client config (e.g. clientConfig.protocol(RedisProtocol.RESP3)) so the connection negotiates RESP3.
If RESP3 cannot be used (old Redis server < 6.0, restrictive proxy), remove the .cache(...) / .cacheConfig(...) calls from the builder.
Verify the Redis server supports RESP3 by running HELLO 3; upgrade the server if needed.

Example fix

// before
RedisClient client = RedisClient.builder()
    .protocol(RedisProtocol.RESP2)
    .cache(CacheClient.builder().maxSize(1000).build())
    .build(); // throws
// after
RedisClient client = RedisClient.builder()
    .protocol(RedisProtocol.RESP3)
    .cache(CacheClient.builder().maxSize(1000).build())
    .build();

Defensive patterns

Strategy: validation

Validate before calling

if (cache != null && clientConfig != null && clientConfig.getProtocol() != RedisProtocol.RESP3) {
  throw new IllegalStateException("Client-side caching requires RESP3; set protocol(RESP3)");
}

Prevention

Always pair .cache(...) with .protocol(RESP3) (or ClientConfig.builder().resp3()) in the same builder call.
Confirm target Redis servers are >= 6.0 (RESP3-capable) before enabling client-side caching.
Centralize client construction in one factory so RESP2/RESP3 policy is applied in one place.

When it happens

Trigger: Calling RedisClient.builder()/.redisClusterClient.builder() etc. with .cache(...) or .cacheConfig(...) set while the underlying clientConfig is pinned to RESP2 (protocol set to RESP2) or otherwise cannot negotiate RESP3, then calling build().

Common situations: Upgrading an existing RESP2-based client to add client-side caching; copy-pasting a cache-enabled example into an app whose connection was configured with Protocol.RESP2 for compatibility with older servers or proxies; Redis servers or intermediaries that do not support HELLO/RESP3.

Related errors

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

Appendix: source

Thrown at src/main/java/redis/clients/jedis/builders/AbstractClientBuilder.java:352

  public T searchDialect(int searchDialect) {
    if (searchDialect == 0) {
      throw new IllegalArgumentException("DIALECT=0 cannot be set.");
    }
    this.searchDialect = searchDialect;
    return self();
  }

  /**
   * Validates common configuration parameters.
   * <p>
   * This method can be called by concrete builders to validate the common configuration before
   * building the client.
   * @throws IllegalArgumentException if any common configuration is invalid
   */
  protected void validateCommonConfiguration() {
    if (cache != null || cacheConfig != null) {
      if (clientConfig != null && !canNegotiateResp3(clientConfig)) {
        throw new IllegalArgumentException("Client-side caching is only supported with RESP3.");
      }
    }
  }

  /**
   * Whether the supplied config can result in a RESP3 connection: either the user explicitly
   * requested RESP3, or the protocol is unspecified and auto-negotiation is enabled.
   */
  private static boolean canNegotiateResp3(JedisClientConfig config) {
    RedisProtocol protocol = config.getRedisProtocol();
    if (protocol == RedisProtocol.RESP3) return true;
    return protocol == null && config.isAutoNegotiateProtocol();
  }
}

View on GitHub (pinned to 6dac31d4c2)