redis/jedis · error · UnsupportedOperationException

Multi-shard command is only supported in…

Error message

Multi-shard command is only supported in ClusterCommandExecutor

What it means

executeMultiShardCommand runs a multi-key command (del, exists, mget, mset, touch, unlink) split across shards and merges the per-shard results — behavior implemented only in ClusterCommandExecutor. If the client's executor is any other implementation, it throws UnsupportedOperationException instead of producing incorrect cross-slot results.

Solutions

Ensure the client is built with ClusterCommandExecutor (default RedisClusterClient builder).
For non-cluster executors, issue the multi-key command directly (single endpoint) rather than via multi-shard execution.
Add an instanceof ClusterCommandExecutor check before using multi-key cross-shard helpers.

Example fix

// before
MultiDbClient client = builder.build(); // non-cluster executor
client.mget("k1", "k2", "k3"); // throws when routed via multi-shard path

// after
// use mget on a UnifiedJedis/Jedis backed by a single endpoint,
// or a RedisClusterClient for cross-slot mget support.

Defensive patterns

Strategy: fallback

Validate before calling

if (!(client instanceof RedisClusterClient)) {
  // multi-key calls must not go through the multi-shard path
  return singleEndpointMget(keys);
}

Type guard

boolean supportsMultiShard = client instanceof RedisClusterClient;

Try / catch

try {
  return client.mget(keys);
} catch (UnsupportedOperationException e) {
  return issueDirectMultiKeyCommand(keys); // non-cluster path
}

Prevention

Only use cross-slot multi-key helpers on RedisClusterClient.
In MultiDbClient/standalone code, call plain mget/del on the active endpoint.
Write tests that exercise every multi-key helper you use against the actual executor.

When it happens

Trigger: Calling any multi-key convenience method (del, exists, mget, mset, touch, unlink) with keys in different slots while the underlying executor is not a ClusterCommandExecutor (custom/substituted executor).

Common situations: MultiDbClient or standalone setups reusing cluster-era multi-key code; custom executors injected for testing or instrumentation; failover/multi-db configurations where keys need not map to slots.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

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

Appendix: source

Thrown at src/main/java/redis/clients/jedis/RedisClusterClient.java:297

   * @param <T> the return type of the command
   * @return the aggregated reply from all primary nodes
   * @throws UnsupportedOperationException if the executor is not a ClusterCommandExecutor
   */
  public final <T> T broadcastCommand(CommandObject<T> commandObject) {
    if (!(executor instanceof ClusterCommandExecutor)) {
      throw new UnsupportedOperationException(
          "Broadcast command is only supported in ClusterCommandExecutor");
    }
    return ((ClusterCommandExecutor) executor).broadcastCommand(commandObject, true);
  }

  // ==================== Multi-Shard Command Methods ====================
  // These methods execute commands across multiple Redis cluster shards when keys
  // hash to different slots, aggregating the results appropriately.

  private <T> T executeMultiShardCommand(List<CommandObject<T>> commandObjects) {
    if (!(executor instanceof ClusterCommandExecutor)) {
      throw new UnsupportedOperationException(
          "Multi-shard command is only supported in ClusterCommandExecutor");
    }
    return ((ClusterCommandExecutor) executor).executeMultiShardCommand(commandObjects);
  }

  /**
   * {@inheritDoc}
   * <p>
   * This override automatically splits the keys by hash slot and executes DEL on each shard,
   * aggregating the results (sum of deleted keys).
   * </p>
   */
  @Override
  public long del(String... keys) {
    return executeMultiShardCommand(getClusterCommandObjects().delMultiShard(keys));
  }

  /**

View on GitHub (pinned to 6dac31d4c2)