redis/jedis · error · IllegalArgumentException

Max attempts must be positive for cluster mode

Error message

Max attempts must be positive for cluster mode

What it means

The cluster builder's maxAttempts controls how many times command execution is retried on failures during topology/redirect handling. validateSpecificConfiguration() rejects values of zero or less, since a non-positive maxAttempts would make cluster command execution immediately give up or behave incorrectly.

Solutions

Set maxAttempts to a positive integer, e.g. .maxAttempts(5) (the cluster default is 5).
Clamp or validate values loaded from configuration: maxAttempts = Math.max(1, configuredValue).
Do not use maxAttempts to disable retries; instead configure maxTotalRetriesDuration for time-bounded retrying.

Example fix

// before
int attempts = Integer.parseInt(props.getProperty("cluster.maxAttempts", "0"));
builder.maxAttempts(attempts).build(); // throws when 0
// after
int attempts = Math.max(1, Integer.parseInt(props.getProperty("cluster.maxAttempts", "5")));
builder.maxAttempts(attempts).build();

Defensive patterns

Strategy: validation

Validate before calling

if (maxAttempts <= 0) {
  throw new IllegalArgumentException("maxAttempts must be >= 1 (cluster default is 5)");
}

Prevention

Use the cluster default (5) unless you have a measured reason to change it.
Clamp config-sourced values: maxAttempts = Math.max(1, value).
Never encode 'disable retries' as 0; use maxTotalRetriesDuration instead.

When it happens

Trigger: Calling RedisClusterClient.builder().maxAttempts(0) or .maxAttempts(-1) (e.g. maxAttempts read from a config file or computed value that resolves to 0 or a negative number), then build().

Common situations: maxAttempts loaded from properties/env where a missing value defaults to 0; user setting 0 believing it means 'unlimited retries'; sign error when computing attempts from a duration.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

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

Appendix: source

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

    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)