redis/node-redis · error · Error

Client Side Caching is only supported with RESP3

Error message

Client Side Caching is only supported with RESP3

What it means

Thrown by RedisClusterSlots.#validateOptions during cluster construction when clientSideCache is configured but the negotiated RESP version is not 3. Redis Client Side Caching (CSC / tracking) requires the RESP3 protocol, which must be explicitly requested via the RESP: 3 option.

Solutions

  1. Set RESP: 3 on the cluster options (and on every node configuration) when using clientSideCache.
  2. Verify the Redis server version is >= 6.0 with RESP3 support enabled.
  3. If you cannot move to RESP3, remove the clientSideCache option.
  4. Ensure RESP is not overridden to 2 at the per-node RedisClusterClientOptions level.

Example fix

// before
createCluster({ rootNodes, clientSideCache: { ... } }); // RESP defaults, not 3 -> throws

// after
createCluster({ rootNodes, RESP: 3, clientSideCache: { ... } });
Defensive patterns

Strategy: validation

Validate before calling

const resp = options.RESP ?? 2;
if (options.clientSideCache && resp !== 3) {
  throw new Error('Enable RESP: 3 to use clientSideCache, or remove clientSideCache.');
}

Type guard

function cscConfigValid(opts: { clientSideCache?: unknown; RESP?: number }): boolean {
  return !opts.clientSideCache || (opts.RESP ?? 2) === 3;
}

Prevention

When it happens

Trigger: Passing createCluster({ ..., clientSideCache: {...}, RESP: 2 }) or omitting RESP (which defaults to a non-3 value) while also passing a clientSideCache provider. The validation runs in the constructor before any connection is made.

Common situations: Enabling client-side caching without knowing it is RESP3-only; copy-pasting a CSC config into an existing cluster that pins RESP: 2 for compatibility; default RESP not being 3 in the current library version.

Related errors

AI-assisted analysis of redis/node-redis@90fd0652bc (2026-08-11). Data as JSON: /api/errors/0921fca62d0af0f1. Report an issue: GitHub.

Appendix: source

Thrown at packages/client/lib/cluster/cluster-slots.ts:272

  readonly scanCursors = new Map<string, ScanCursorEntry>();
  #cursorTokenSeq = 0;
  #topologyRefreshPromise?: Promise<boolean | void>;

  #isOpen = false;

  get isOpen() {
    return this.#isOpen;
  }

  #isReady = false;

  get isReady() {
    return this.#isReady;
  }

  #validateOptions(options?: RedisClusterOptions<M, F, S, RESP, TYPE_MAPPING>) {
    if (options?.clientSideCache && (options?.RESP ?? DEFAULT_RESP) !== 3) {
      throw new Error('Client Side Caching is only supported with RESP3');
    }
  }

  constructor(
    options: RedisClusterOptions<M, F, S, RESP, TYPE_MAPPING>,
    emit: EventEmitter['emit'],
    clusterClientId: string
  ) {
    this.#validateOptions(options);
    this.#options = options;
    this.#himportRegistry = options.himportRegistry ?? new FieldsetRegistry();
    this.#clusterClientId = clusterClientId;
    this.#reconnectionTracker = new ClusterReconnectionTracker(options.topologyRefreshOnReconnectionAttemptStrategy);

    if (options?.clientSideCache) {
      if (options.clientSideCache instanceof PooledClientSideCacheProvider) {
        this.clientSideCache = options.clientSideCache;
      } else {

View on GitHub (pinned to 90fd0652bc)