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

#validateOptions runs during client construction and enforces that the client-side cache (options.clientSideCache) is only enabled when the RESP version is 3. Client-side caching relies on RESP3 PUSH messages (invalidation notifications) sent by the server, which do not exist in RESP2; enabling the cache on RESP2 would silently never receive invalidations. The default RESP version is 3, so this fires only when RESP is explicitly set to 2 alongside clientSideCache.

Source

Thrown at packages/client/lib/client/index.ts:794

      this.#queue.addPushHandler((push: Array<any>): boolean => {
        if (push[0].toString() !== 'invalidate') return false;

        if (push[1] !== null) {
          for (const key of push[1]) {
            this.emit('invalidate', key);
          }
        } else {
          this.emit('invalidate', null);
        }
        return true
      });
    }
  }

  #validateOptions(options?: RedisClientOptions<M, F, S, RESP, TYPE_MAPPING>) {
    const resp = options?.RESP ?? DEFAULT_RESP;
    if (options?.clientSideCache && resp !== 3) {
      throw new Error('Client Side Caching is only supported with RESP3');
    }
    if (options?.emitInvalidate && resp !== 3) {
      throw new Error('emitInvalidate is only supported with RESP3');
    }
    if (options?.clientSideCache && options?.emitInvalidate) {
      throw new Error('emitInvalidate is not supported (or necessary) when clientSideCache is enabled');
    }
    if (options?.maintNotifications && options?.maintNotifications !== 'disabled' && resp !== 3) {
      throw new Error('Graceful Maintenance is only supported with RESP3');
    }
  }

  #initiateOptions(options: RedisClientOptions<M, F, S, RESP, TYPE_MAPPING> = {}): RedisClientOptions<M, F, S, RESP, TYPE_MAPPING> {

    // Convert username/password to credentialsProvider if no credentialsProvider is already in place
    if (!options.credentialsProvider && (options.username || options.password)) {

      options.credentialsProvider = {

View on GitHub (pinned to bb5beb5657)

Solutions

  1. Remove the RESP:2 override (or set RESP:3) so the client negotiates RESP3 and the cache works.
  2. Upgrade the Redis server to >= 6.0 with RESP3 support if needed.
  3. If RESP2 is mandatory, do not enable clientSideCache (it cannot function without RESP3 invalidations).

Example fix

// before
createClient({ RESP: 2, clientSideCache: new BasicClientSideCache() });

// after
createClient({ clientSideCache: new BasicClientSideCache() }); // RESP3 is the default
Defensive patterns

Strategy: validation

Validate before calling

function makeClient(opts) {
  if (opts.clientSideCache && (opts.RESP ?? 3) !== 3) {
    throw new TypeError('clientSideCache requires RESP3');
  }
  return createClient(opts);
}

Prevention

When it happens

Trigger: `createClient({ RESP: 2, clientSideCache: new BasicClientSideCache() })`; a base config that sets isolationLevel/RESP to 2 combined with a cache config that turns the cache on.

Common situations: Forcing RESP2 for compatibility with an old server while also wanting client-side caching; layered config where one layer pins RESP and another enables the cache; migrating to client-side caching on a server that does not support RESP3.

Related errors

AI-assisted analysis of redis/node-redis@bb5beb5657 (2026-08-03). Data as JSON: /data/errors/ce80bd86a93d1672.json. Report an issue: GitHub.