{"record":{"id":"29d1a4bb40e32de4","repo":"redis/jedis","slug":"client-side-caching-is-only-supported-with-resp3-29d1a4","errorCode":null,"errorMessage":"Client-side caching is only supported with RESP3.","messagePattern":"Client-side caching is only supported with RESP3\\.","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"src/main/java/redis/clients/jedis/builders/AbstractClientBuilder.java","lineNumber":352,"sourceCode":"  public T searchDialect(int searchDialect) {\n    if (searchDialect == 0) {\n      throw new IllegalArgumentException(\"DIALECT=0 cannot be set.\");\n    }\n    this.searchDialect = searchDialect;\n    return self();\n  }\n\n  /**\n   * Validates common configuration parameters.\n   * <p>\n   * This method can be called by concrete builders to validate the common configuration before\n   * building the client.\n   * @throws IllegalArgumentException if any common configuration is invalid\n   */\n  protected void validateCommonConfiguration() {\n    if (cache != null || cacheConfig != null) {\n      if (clientConfig != null && !canNegotiateResp3(clientConfig)) {\n        throw new IllegalArgumentException(\"Client-side caching is only supported with RESP3.\");\n      }\n    }\n  }\n\n  /**\n   * Whether the supplied config can result in a RESP3 connection: either the user explicitly\n   * requested RESP3, or the protocol is unspecified and auto-negotiation is enabled.\n   */\n  private static boolean canNegotiateResp3(JedisClientConfig config) {\n    RedisProtocol protocol = config.getRedisProtocol();\n    if (protocol == RedisProtocol.RESP3) return true;\n    return protocol == null && config.isAutoNegotiateProtocol();\n  }\n}\n","sourceCodeStart":334,"sourceCodeEnd":367,"githubUrl":"https://github.com/redis/jedis/blob/6dac31d4c224fb3257c216f3985340c6f500cdcb/src/main/java/redis/clients/jedis/builders/AbstractClientBuilder.java#L334-L367","documentation":"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.","triggerScenarios":"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().","commonSituations":"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.","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."],"exampleFix":"// before\nRedisClient client = RedisClient.builder()\n    .protocol(RedisProtocol.RESP2)\n    .cache(CacheClient.builder().maxSize(1000).build())\n    .build(); // throws\n// after\nRedisClient client = RedisClient.builder()\n    .protocol(RedisProtocol.RESP3)\n    .cache(CacheClient.builder().maxSize(1000).build())\n    .build();","handlingStrategy":"validation","validationCode":"if (cache != null && clientConfig != null && clientConfig.getProtocol() != RedisProtocol.RESP3) {\n  throw new IllegalStateException(\"Client-side caching requires RESP3; set protocol(RESP3)\");\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["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."],"tags":["jedis","client-side-caching","resp3","configuration","builder"],"backgroundTag":"unsupported-config-value","analyzedSha":"6dac31d4c224fb3257c216f3985340c6f500cdcb","analyzedAt":"2026-09-08T04:55:01.204Z","contentChangedAt":"2026-09-08T04:55:01.204Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}