redis/jedis · error · IllegalArgumentException

Max total retries duration cannot be negative for cluster…

Error message

Max total retries duration cannot be negative for cluster mode

What it means

maxTotalRetriesDuration bounds the total wall-clock time spent retrying a cluster command. validateSpecificConfiguration() throws this IllegalArgumentException when the supplied Duration is negative; a negative duration makes no temporal sense and would corrupt the retry deadline computation.

Solutions

Pass a non-negative Duration, e.g. Duration.ofSeconds(2); use Duration.ZERO only if you truly want no retry window.
Validate or clamp durations from configuration: if (d.isNegative()) throw/clamp before building.
Use Duration.parse() on well-formed ISO-8601 strings (e.g. PT2S) and reject negative input at config-load time.

Example fix

// before
builder.maxTotalRetriesDuration(Duration.ofSeconds(-2)).build(); // throws
// after
builder.maxTotalRetriesDuration(Duration.ofSeconds(2)).build();

Defensive patterns

Strategy: validation

Validate before calling

if (maxTotalRetriesDuration != null && maxTotalRetriesDuration.isNegative()) {
  throw new IllegalArgumentException("maxTotalRetriesDuration must be non-negative");
}

Prevention

Build durations with Duration.ofSeconds/ofMillis constants, never by arithmetic that can go negative.
Sanitize ISO-8601 duration strings from config before Duration.parse.
Document non-negative requirements where durations are entered by operators.

When it happens

Trigger: Calling RedisClusterClient.builder().maxTotalRetriesDuration(Duration.ofSeconds(-1)) or any negative Duration, then build().

Common situations: A duration parsed from a config string with a leading minus sign; arithmetic on durations (e.g. subtracting) yielding a negative value; confusing Duration.ofMillis(-1) sentinel values.

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

Appendix: source

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

    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)