{"record":{"id":"bbc7524fe3a9cf45","repo":"redis/jedis","slug":"multi-shard-command-is-only-supported-in-clusterco","errorCode":null,"errorMessage":"Multi-shard command is only supported in ClusterCommandExecutor","messagePattern":"Multi-shard command is only supported in ClusterCommandExecutor","errorType":"exception","errorClass":"UnsupportedOperationException","httpStatus":null,"severity":"error","filePath":"src/main/java/redis/clients/jedis/RedisClusterClient.java","lineNumber":297,"sourceCode":"   * @param <T> the return type of the command\n   * @return the aggregated reply from all primary nodes\n   * @throws UnsupportedOperationException if the executor is not a ClusterCommandExecutor\n   */\n  public final <T> T broadcastCommand(CommandObject<T> commandObject) {\n    if (!(executor instanceof ClusterCommandExecutor)) {\n      throw new UnsupportedOperationException(\n          \"Broadcast command is only supported in ClusterCommandExecutor\");\n    }\n    return ((ClusterCommandExecutor) executor).broadcastCommand(commandObject, true);\n  }\n\n  // ==================== Multi-Shard Command Methods ====================\n  // These methods execute commands across multiple Redis cluster shards when keys\n  // hash to different slots, aggregating the results appropriately.\n\n  private <T> T executeMultiShardCommand(List<CommandObject<T>> commandObjects) {\n    if (!(executor instanceof ClusterCommandExecutor)) {\n      throw new UnsupportedOperationException(\n          \"Multi-shard command is only supported in ClusterCommandExecutor\");\n    }\n    return ((ClusterCommandExecutor) executor).executeMultiShardCommand(commandObjects);\n  }\n\n  /**\n   * {@inheritDoc}\n   * <p>\n   * This override automatically splits the keys by hash slot and executes DEL on each shard,\n   * aggregating the results (sum of deleted keys).\n   * </p>\n   */\n  @Override\n  public long del(String... keys) {\n    return executeMultiShardCommand(getClusterCommandObjects().delMultiShard(keys));\n  }\n\n  /**","sourceCodeStart":279,"sourceCodeEnd":315,"githubUrl":"https://github.com/redis/jedis/blob/6dac31d4c224fb3257c216f3985340c6f500cdcb/src/main/java/redis/clients/jedis/RedisClusterClient.java#L279-L315","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","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."],"exampleFix":"// before\nMultiDbClient client = builder.build(); // non-cluster executor\nclient.mget(\"k1\", \"k2\", \"k3\"); // throws when routed via multi-shard path\n\n// after\n// use mget on a UnifiedJedis/Jedis backed by a single endpoint,\n// or a RedisClusterClient for cross-slot mget support.","handlingStrategy":"fallback","validationCode":"if (!(client instanceof RedisClusterClient)) {\n  // multi-key calls must not go through the multi-shard path\n  return singleEndpointMget(keys);\n}","typeGuard":"boolean supportsMultiShard = client instanceof RedisClusterClient;","tryCatchPattern":"try {\n  return client.mget(keys);\n} catch (UnsupportedOperationException e) {\n  return issueDirectMultiKeyCommand(keys); // non-cluster path\n}","preventionTips":["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."],"tags":["unsupported-operation","cluster","multi-key"],"backgroundTag":"unsupported-operation","analyzedSha":"6dac31d4c224fb3257c216f3985340c6f500cdcb","analyzedAt":"2026-09-08T04:55:01.204Z","contentChangedAt":"2026-09-08T04:55:01.204Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}