redis/node-redis · error · Error

Graceful Maintenance is only supported with RESP3

Error message

Graceful Maintenance is only supported with RESP3

What it means

maintNotifications uses RESP3 push messages for graceful maintenance (server-side disconnect hints). The literal value 'disabled' is exempt (it explicitly opts out). Any other value requires RESP3, and #validateOptions rejects it otherwise.

Solutions

1. Set RESP: 3 (server must support graceful maintenance).
2. Or set maintNotifications: 'disabled' to explicitly opt out.
3. Or omit the option entirely if you do not need maintenance notifications.

Example fix

// before
createClient({ maintNotifications: 'graceful' });

// after
createClient({ maintNotifications: 'graceful', RESP: 3 });

function validateMaintOptions(options) {
  const resp = options?.RESP ?? 3;
  if (options?.maintNotifications && options.maintNotifications !== 'disabled' && resp !== 3) {
    throw new Error('maintNotifications (other than disabled) requires RESP: 3');
  }
  return options;
}

When it happens

Trigger: createClient({ maintNotifications: 'graceful', RESP: 2 }) or any non-'disabled' maintNotifications value with the resolved RESP below 3.

Common situations: Forcing RESP: 2 for compatibility while still wanting maintenance mode; older redis server; misreading 'disabled' as the default.

Related errors

• Client Side Caching is only supported with RESP3
• emitInvalidate is only supported with RESP3
• emitInvalidate is not supported (or necessary) when…
• expirationRefreshRatio must be greater or equal to 0
• expirationRefreshRatio must be less than or equal to 1

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

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