redis/jedis · error · IllegalArgumentException

Topology refresh period cannot be negative for cluster mode

Error message

Topology refresh period cannot be negative for cluster mode

What it means

topologyRefreshPeriod controls how often RedisClusterClient proactively refreshes cluster slot topology. validateSpecificConfiguration() throws this IllegalArgumentException when the period is negative, since a negative refresh interval cannot be scheduled and would break the topology refresh scheduler.

Solutions

Pass a non-negative Duration, e.g. .topologyRefreshPeriod(Duration.ofSeconds(60)).
To effectively disable periodic refresh, use Duration.ZERO (or omit the setting) rather than a negative period.
Validate config-sourced durations with duration.isNegative() before passing them to the builder.

Example fix

// before
builder.topologyRefreshPeriod(Duration.ofMinutes(-1)).build(); // throws
// after
builder.topologyRefreshPeriod(Duration.ofMinutes(1)).build();

Defensive patterns

Strategy: validation

Validate before calling

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

Prevention

Use Duration.ZERO to disable periodic refresh, never negative values.
Validate all Duration-typed config fields once at load time.
Prefer explicit config keys for 'enabled/disabled' rather than sentinel negative durations.

When it happens

Trigger: Calling RedisClusterClient.builder().topologyRefreshPeriod(Duration.ofMinutes(-5)) or another negative Duration, then build().

Common situations: Negative value parsed from configuration or computed by subtracting durations; misuse of a negative sentinel meaning 'disabled' when Duration.ZERO or a dedicated flag should be used instead.

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

Appendix: source

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

  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)