redis/jedis · error · UnsupportedOperationException

Support only execute to replica in ClusterCommandExecutor

Error message

Support only execute to replica in ClusterCommandExecutor

What it means

executeCommandToReplica routes a command to a replica and only works when the client's CommandExecutor is a ClusterCommandExecutor. On any other executor type (simple, retry, multi-db, failover), it throws UnsupportedOperationException. This is a capability check guarding a cluster-only feature.

Solutions

Call executeCommandToReplica only on a cluster-based client (JedisCluster / RedisClusterClient with ClusterCommandExecutor)
For standalone clients use readFrom(ReadFrom.REPLICA) configuration or normal read commands instead
Check `executor instanceof ClusterCommandExecutor` (or client type) before invoking and provide a fallback path

Example fix

// before
client.executeCommandToReplica(commandObject); // UnsupportedOperationException on standalone
// after
if (client instanceof RedisClusterClient) {
  client.executeCommandToReplica(commandObject);
} else {
  client.executeCommand(commandObject); // standard read path
}

Defensive patterns

Strategy: type-guard

Validate before calling

boolean replicaRoutingSupported = client instanceof RedisClusterClient || client instanceof JedisCluster;

Type guard

boolean supportsReplicaRead(UnifiedJedis client) { return client instanceof JedisCluster; }

Try / catch

try {
  return client.executeCommandToReplica(cmd);
} catch (UnsupportedOperationException e) {
  return client.executeCommand(cmd); // fallback to normal read path
}

Prevention

Only route replica reads on cluster clients
Configure ReadFrom.REPLICA on standalone clients that need replica reads
Keep cluster-only call sites separated from generic UnifiedJedis utilities

When it happens

Trigger: Calling executeCommandToReplica(commandObject) on a UnifiedJedis (e.g. Jedis, RedisClient, MultiDbClient) whose executor is not a ClusterCommandExecutor.

Common situations: Shared utility code written for JedisCluster being reused with a standalone RedisClient; a client built via AbstractClientBuilder with the default non-cluster executor; refactoring that swapped the executor without updating replica-read call sites.

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/08236739a84302b6. Report an issue: GitHub.

Appendix: source

Thrown at src/main/java/redis/clients/jedis/JedisCluster.java:501

            (ClusterCommandObjects) commandObjects,
            commandFlagsRegistry,
            executorService
    );
  }

  /**
   * @param doMulti param
   * @return nothing
   * @throws UnsupportedOperationException
   */
  @Override
  public AbstractTransaction transaction(boolean doMulti) {
    throw new UnsupportedOperationException();
  }

  public final <T> T executeCommandToReplica(CommandObject<T> commandObject) {
    if (!(executor instanceof ClusterCommandExecutor)) {
      throw new UnsupportedOperationException("Support only execute to replica in ClusterCommandExecutor");
    }
    return ((ClusterCommandExecutor) executor).executeCommandToReplica(commandObject);
  }
}

View on GitHub (pinned to 6dac31d4c2)