redis/jedis · error · UnsupportedOperationException

Cache is required to build CacheConnection.

Error message

Cache is required to build CacheConnection.

What it means

The no-arg CacheConnection.builder() overload is intentionally disabled: client-side caching fundamentally needs a Cache to receive invalidation pushes, so calling it always throws UnsupportedOperationException. It exists only for testing/framework symmetry with other Connection types (@VisibleForTesting). Production code must use the builder(Cache) overload.

Solutions

1. Switch to CacheConnection.builder(cache), supplying a Cache built via CacheFactory.getCache(cacheConfig).
2. If your generic builder framework calls no-arg builder(), special-case CacheConnection to invoke builder(cache) instead.
3. Treat the exception as a signal that client-side caching cannot be used without a cache; if you do not need caching, use a plain connection type.

Example fix

// before
CacheConnection.Builder b = CacheConnection.builder(); // always throws
// after
Cache cache = CacheFactory.getCache(new CacheConfig());
CacheConnection.Builder b = CacheConnection.builder(cache);

if (cache == null) { throw new UnsupportedOperationException("Use CacheConnection.builder(cache) — client-side caching requires a Cache"); }
CacheConnection connection = CacheConnection.builder(cache);

When it happens

Trigger: Calling CacheConnection.builder() with no arguments anywhere in application code; generic connection-building frameworks that reflectively invoke a no-arg builder() method for all connection types.

Common situations: Migrating code that built other connection types (e.g. DefaultJedisSocketFactory-based connections) with a parameterless builder and reusing the same pattern; a factory using reflection/strategy to call builder() uniformly across connection implementations.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

• Client-side caching is only supported with RESP3.
• Not supported in cluster mode.
• HostAndPort is required when no socketFactory is provided
• Support only execute to replica in ClusterCommandExecutor
• Command '' with request policy cannot be executed in…

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

Appendix: source

Thrown at src/main/java/redis/clients/jedis/csc/CacheConnection.java:57

    @Override
    public Builder clientConfig(JedisClientConfig clientConfig) {
      super.clientConfig(clientConfig);
      return this;
    }

    @Override
    protected Connection createConnection() {
      return new CacheConnection(this);
    }
  }

  public static Builder builder(Cache cache) {
    return new Builder(cache);
  }

  @VisibleForTesting
  public static Builder builder() {
    throw new UnsupportedOperationException("Cache is required to build CacheConnection.");
  }

  private final Cache cache;
  private ReentrantLock lock;
  private static final String REDIS = "redis";
  private static final String MIN_REDIS_VERSION = "7.4";

  public CacheConnection(final JedisSocketFactory socketFactory, JedisClientConfig clientConfig, Cache cache) {
    super(socketFactory, clientConfig);

    this.cache = Objects.requireNonNull(cache);
    initializeClientSideCache();
  }

  private CacheConnection(Builder builder) {
    super(builder);
    this.cache = builder.getCache();
  }

View on GitHub (pinned to 6dac31d4c2)