redis/jedis · error · JedisConnectionException

Maintenance notifications: events not supported on server

Error message

Maintenance notifications: events not supported on server

What it means

Jedis enables server-side maintenance notifications (CLIENT MAINT_NOTIFICATIONS) after the handshake so the server can push MOVING/MIGRATED events. If the server rejects the registration with a JedisDataException and the visitor is in strict mode, Jedis rethrows it as a JedisConnectionException meaning the connected server does not support maintenance push events.

Solutions

1. Set strict mode to false so unsupported servers degrade gracefully (events disabled, logged at debug)
2. Upgrade the Redis server to a version that supports CLIENT MAINT_NOTIFICATIONS (e.g. managed Redis with maintenance events)
3. If strict mode is required, target only endpoints known to support maintenance notifications

Example fix

// before
MaintenanceAwareVisitor visitor = new MaintenanceAwareVisitor(/* strict */ true);
// after
MaintenanceAwareVisitor visitor = new MaintenanceAwareVisitor(/* strict */ false); // tolerate servers without maintenance events

// Detect support before relying on events
try (Jedis j = new Jedis(host, port)) {
  String reply = j.clientMaintenanceNotificationsOn(); // will throw if unsupported
}

try {
  visitor.visitAfterHandshake(connection);
} catch (JedisConnectionException e) {
  if (e.getMessage().contains("events not supported")) {
    logger.warn("Server lacks maintenance events; continuing without them");
  } else {
    throw e;
  }
}

When it happens

Trigger: Connecting with maintenance notifications enabled (strict mode) to a Redis server or proxy that does not implement CLIENT MAINT_NOTIFICATIONS; the server replies with an error to the registration command during visitAfterHandshake.

Common situations: Pointing a maintenance-aware client at an older Redis version, non-managed Redis, or a proxy that strips the MAINT_NOTIFICATIONS subcommand; forgetting to disable strict mode in test or on-prem environments.

Related errors

• null is not a valid argument.
• HELLO response is missing the protocol version field
• Failed to create socket.
• HashImport ' ' has been discarded
• HashImport ' ' expects values but got

AI-assisted analysis of redis/jedis@6dac31d4c2 (2026-09-08). Data as JSON: /api/errors/b8d34d7802df2bf4. Report an issue: GitHub.

Appendix: source

Thrown at src/main/java/redis/clients/jedis/MaintenanceAwareVisitor.java:102

      maintenanceEventListeners.add(controller);

      // The server must accept CLIENT MAINT_NOTIFICATIONS ON. Pre-register the consumer so a
      // push
      // frame the server emits immediately on accepting the subscription cannot race ahead.
      MaintenanceEventConsumer consumer = new MaintenanceEventConsumer(connection,
          maintenanceEventListeners);
      connection.addPushConsumer(consumer);

      connection.sendCommand(Command.CLIENT, "MAINT_NOTIFICATIONS", "ON", "moving-endpoint-type",
        resolveEndpointType(connection, mConfig));
      try {
        connection.getStatusCodeReply();
        keepOverrides = true;
      } catch (JedisDataException e) {
        connection.removePushConsumer(consumer);

        if (strict) {
          throw new JedisConnectionException(
              "Maintenance notifications: events not supported on server", e);
        }
        logger.debug(
          "Maintenance notifications disabled: server rejected CLIENT MAINT_NOTIFICATIONS ({}).",
          e.getMessage());
      }
    } finally {
      if (!keepOverrides) {
        // Undo the rebind overlay installed before the handshake — this connection does NOT support
        // maintenance notifications.
        ChainedTimeoutSource dts = connection.getTimeoutSource();
        dts.removeOverride(dts.seekBy(controller));
        dts.removeOverride(dts.seekBy(ExpiringTimeoutSource.class));
      }
    }
  }

  private static boolean isMaintenanceEnabled(MaintenanceNotificationsConfig maintenanceConfig) {

View on GitHub (pinned to 6dac31d4c2)