{"record":{"id":"f9226b1f472ce0b0","repo":"redis/jedis","slug":"topology-refresh-period-cannot-be-negative-for-clu","errorCode":null,"errorMessage":"Topology refresh period cannot be negative for cluster mode","messagePattern":"Topology refresh period cannot be negative for cluster mode","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"src/main/java/redis/clients/jedis/builders/ClusterClientBuilder.java","lineNumber":154,"sourceCode":"  protected void validateSpecificConfiguration() {\n    validateCommonConfiguration();\n\n    if (nodes == null || nodes.isEmpty()) {\n      throw new IllegalArgumentException(\n          \"At least one cluster node must be specified for cluster mode\");\n    }\n\n    if (maxAttempts <= 0) {\n      throw new IllegalArgumentException(\"Max attempts must be positive for cluster mode\");\n    }\n\n    if (maxTotalRetriesDuration != null && maxTotalRetriesDuration.isNegative()) {\n      throw new IllegalArgumentException(\n          \"Max total retries duration cannot be negative for cluster mode\");\n    }\n\n    if (topologyRefreshPeriod != null && topologyRefreshPeriod.isNegative()) {\n      throw new IllegalArgumentException(\n          \"Topology refresh period cannot be negative for cluster mode\");\n    }\n  }\n\n}\n","sourceCodeStart":136,"sourceCodeEnd":160,"githubUrl":"https://github.com/redis/jedis/blob/6dac31d4c224fb3257c216f3985340c6f500cdcb/src/main/java/redis/clients/jedis/builders/ClusterClientBuilder.java#L136-L160","documentation":"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.","triggerScenarios":"Calling RedisClusterClient.builder().topologyRefreshPeriod(Duration.ofMinutes(-5)) or another negative Duration, then build().","commonSituations":"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.","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."],"exampleFix":"// before\nbuilder.topologyRefreshPeriod(Duration.ofMinutes(-1)).build(); // throws\n// after\nbuilder.topologyRefreshPeriod(Duration.ofMinutes(1)).build();","handlingStrategy":"validation","validationCode":"if (topologyRefreshPeriod != null && topologyRefreshPeriod.isNegative()) {\n  throw new IllegalArgumentException(\"topologyRefreshPeriod must be non-negative\");\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["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."],"tags":["jedis","cluster","builder","topology","configuration"],"backgroundTag":"invalid-config-value","analyzedSha":"6dac31d4c224fb3257c216f3985340c6f500cdcb","analyzedAt":"2026-09-08T04:55:01.204Z","contentChangedAt":"2026-09-08T04:55:01.204Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}