redis/node-redis · error · Error

Graceful Maintenance is only supported with RESP3

Error message

Graceful Maintenance is only supported with RESP3

What it means

#validateOptions rejects `maintNotifications` (when not 'disabled') unless RESP is 3. Graceful Maintenance (enterprise maintenance notifications) depends on RESP3 PUSH messages (e.g. SMIGRATED events) delivered by the server; RESP2 has no push channel for them, so enabling maintenance notifications on RESP2 would silently never fire. Setting maintNotifications to the literal 'disabled' opts out and is allowed with any RESP version.

Source

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

        }
        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
        })
      };
    }

    if (options.database) {

View on GitHub (pinned to bb5beb5657)

Solutions

1. Use RESP3 (the default) when enabling maintNotifications.
2. If RESP2 is mandatory and you do not need maintenance notifications, set `maintNotifications: 'disabled'` to opt out explicitly.
3. Upgrade to a Redis Enterprise / RESP3-capable server.

Example fix

// before
createClient({ RESP: 2, maintNotifications: { /* ... */ } });

// after
createClient({ maintNotifications: { /* ... */ } }); // RESP3 default

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

When it happens

Trigger: `createClient({ RESP: 2, maintNotifications: { /* options */ } })`; any non-'disabled' maintNotifications value combined with RESP:2.

Common situations: Forcing RESP2 for compatibility while wanting enterprise maintenance handling; a shared base config pinning RESP and a feature config enabling maintenance.

Related errors

• Client Side Caching is only supported with RESP3
• emitInvalidate 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

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