redis/node-redis · error · Error

emitInvalidate is not supported (or necessary) when clientSi

Error message

emitInvalidate is not supported (or necessary) when clientSideCache is enabled

What it means

#validateOptions rejects setting both `clientSideCache` and `emitInvalidate` at once. When client-side caching is enabled, the cache provider already consumes 'invalidate' push messages internally to evict stale entries, so a separate emitInvalidate handler is redundant and would double-process the same pushes (or conflict over the push stream). The client tells you emitInvalidate is unnecessary in that mode.

Source

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

          }
        } 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 = {
        type: 'async-credentials-provider',
        credentials: async () => ({
          username: options.username,
          password: options.password
        })
      };

View on GitHub (pinned to bb5beb5657)

Solutions

1. If you use clientSideCache, remove emitInvalidate — the cache already handles invalidation (and emits its own 'invalidate' event on the provider).
2. If you only want raw invalidate events without caching, drop clientSideCache and keep emitInvalidate.
3. Centralize config so the two flags are mutually exclusive.

Example fix

// before
createClient({ clientSideCache: new BasicClientSideCache(), emitInvalidate: true });

// after
createClient({ clientSideCache: new BasicClientSideCache() });

function makeClient(opts) {
  if (opts.clientSideCache && opts.emitInvalidate) {
    throw new TypeError('Do not set emitInvalidate when clientSideCache is enabled');
  }
  return createClient(opts);
}

When it happens

Trigger: `createClient({ clientSideCache: new BasicClientSideCache(), emitInvalidate: true })`; layered config turning both features on.

Common situations: Enabling the cache and also wanting invalidate events 'just in case'; merging two config fragments each enabling one of the features; upgrading from emitInvalidate to the full cache without removing the old flag.

Related errors

• Client Side Caching is only supported with RESP3
• expirationRefreshRatio must be less than or equal to 1
• expirationRefreshRatio must be greater or equal to 0
• tls socket option is set to ${options.socket.tls} which is m
• Invalid protocol

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