redis/jedis · error · IllegalArgumentException

At least one cluster node must be specified for cluster mode

Error message

At least one cluster node must be specified for cluster mode

What it means

RedisClusterClientBuilder requires a seed list of cluster nodes to route commands and discover the cluster topology. validateSpecificConfiguration() throws this IllegalArgumentException during build() when no nodes were provided, because a cluster client cannot function without at least one seed node to contact.

Solutions

1. Provide at least one seed node via .nodes(new HostAndPort("127.0.0.1", 7000)) or .nodes(Set.of(...)) before build().
2. If nodes come from configuration, validate the list is non-empty before constructing the builder.
3. Ensure you are using RedisClusterClient.builder() only when actually connecting to a cluster; otherwise use RedisClient.builder() with a single endpoint.

Example fix

// before
RedisClusterClient client = RedisClusterClient.builder()
    .maxAttempts(5)
    .build(); // throws
// after
RedisClusterClient client = RedisClusterClient.builder()
    .nodes(new HostAndPort("127.0.0.1", 7000))
    .maxAttempts(5)
    .build();

if (nodes == null || nodes.isEmpty()) {
  throw new IllegalArgumentException("Provide at least one cluster node before build()");
}

try {
  client = RedisClusterClient.builder().nodes(nodes).build();
} catch (IllegalArgumentException e) {
  if (e.getMessage().contains("At least one cluster node")) {
    throw new ConfigurationException("cluster nodes missing", e);
  }
  throw e;
}

When it happens

Trigger: Building a RedisClusterClient without calling .nodes(...) (or passing an empty set/list of HostAndPort), then calling build().

Common situations: Copy-pasting a standalone-client example and forgetting the cluster .nodes() call; constructing nodes conditionally from config and getting an empty list when the config section is missing; typos in builder method ordering.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• Max attempts must be positive for cluster mode
• Max total retries duration cannot be negative for cluster…
• Topology refresh period cannot be negative for cluster mode
• At least one sentinel must be specified for Sentinel mode
• HostAndPort is required when no socketFactory is provided

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

Appendix: source

Thrown at src/main/java/redis/clients/jedis/builders/ClusterClientBuilder.java:140

  protected CommandExecutor createDefaultCommandExecutor() {
    if (this.commandFlags == null) {
      this.commandFlags = createDefaultCommandFlagsRegistry();
    }

    Duration effectiveMaxTotalRetriesDuration = (this.maxTotalRetriesDuration == null)
        ? Duration.ofMillis((long) this.clientConfig.getSocketTimeoutMillis() * this.maxAttempts)
        : this.maxTotalRetriesDuration;

    return new ClusterCommandExecutor((ClusterConnectionProvider) this.connectionProvider,
        this.maxAttempts, effectiveMaxTotalRetriesDuration, this.commandFlags);
  }

  @Override
  protected void validateSpecificConfiguration() {
    validateCommonConfiguration();

    if (nodes == null || nodes.isEmpty()) {
      throw new IllegalArgumentException(
          "At least one cluster node must be specified for cluster mode");
    }

    if (maxAttempts <= 0) {
      throw new IllegalArgumentException("Max attempts must be positive for cluster mode");
    }

    if (maxTotalRetriesDuration != null && maxTotalRetriesDuration.isNegative()) {
      throw new IllegalArgumentException(
          "Max total retries duration cannot be negative for cluster mode");
    }

    if (topologyRefreshPeriod != null && topologyRefreshPeriod.isNegative()) {
      throw new IllegalArgumentException(
          "Topology refresh period cannot be negative for cluster mode");
    }
  }

View on GitHub (pinned to 6dac31d4c2)