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

Client Side Caching (clientSideCache) relies on RESP3 server push messages (invalidate notifications). With RESP !== 3 the option is rejected in #validateOptions at client construction. RESP3 is negotiated when options.RESP is 3 or unset-and-negotiated-up.

Solutions

  1. Set RESP: 3 (and ensure the server is redis >= 6 with RESP3 enabled).
  2. Or drop clientSideCache if you must stay on RESP2.

Example fix

// before
createClient({ clientSideCache: myCache });

// after
createClient({ clientSideCache: myCache, RESP: 3 });
Defensive patterns

Strategy: validation

Validate before calling

function validateCscOptions(options) {
  const resp = options?.RESP ?? 3;
  if (options?.clientSideCache && resp !== 3) {
    throw new Error('clientSideCache requires RESP: 3 (redis >= 6)');
  }
  return options;
}

Prevention

When it happens

Trigger: createClient({ clientSideCache: cacheInstance, RESP: 2 }) or any combination where the resolved RESP version is not 3.

Common situations: Forcing RESP: 2 for compatibility with an older server while enabling client-side caching; redis server older than 6.0 that does not support RESP3; legacy config copied into a new app.

Related errors

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

Appendix: 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 90fd0652bc)