redis/jedis · error · IllegalArgumentException

At least one sentinel must be specified for Sentinel mode

Error message

At least one sentinel must be specified for Sentinel mode

What it means

A Sentinel client needs at least one sentinel address to query for the current master location and to subscribe to failover events. SentinelClientBuilder.validateSpecificConfiguration() throws this IllegalArgumentException when the sentinel endpoint set is null or empty at build() time.

Solutions

Provide sentinel endpoints via .sentinels(Set.of(new HostAndPort("sentinel1", 26379), ...)) before build().
Validate the sentinel list is non-empty when parsing from configuration.
Confirm sentinel processes are actually deployed and reachable; the builder requires addresses regardless.

Example fix

// before
RedisSentinelClient client = RedisSentinelClient.builder()
    .masterName("mymaster")
    .build(); // throws: no sentinels
// after
RedisSentinelClient client = RedisSentinelClient.builder()
    .masterName("mymaster")
    .sentinels(Set.of(new HostAndPort("localhost", 26379)))
    .build();

Defensive patterns

Strategy: validation

Validate before calling

if (sentinels == null || sentinels.isEmpty()) {
  throw new IllegalArgumentException("at least one sentinel address is required");
}

Prevention

Parse sentinel addresses with a tokenizer that rejects blank input instead of yielding an empty list.
List at least 3 sentinel endpoints for quorum reliability.
Verify sentinel reachability with a health check at startup.

When it happens

Trigger: Building a RedisSentinelClient without calling .sentinels(...), or with an empty set of HostAndPort entries.

Common situations: Sentinel addresses parsed from config where the sentinel list key is missing or empty; split-string parsing producing an empty list for a blank config value; reusing a standalone connection config in sentinel mode.

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

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

Appendix: source

Thrown at src/main/java/redis/clients/jedis/builders/SentinelClientBuilder.java:104

    return this;
  }

  @Override
  protected ConnectionProvider createDefaultConnectionProvider() {
    return new SentineledConnectionProvider(this.masterName, this.clientConfig, this.cache,
        this.poolConfig, this.sentinels, this.sentinelClientConfig, sentinelReconnectDelay);
  }

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

    if (masterName == null || masterName.trim().isEmpty()) {
      throw new IllegalArgumentException("Master name is required for Sentinel mode");
    }

    if (sentinels == null || sentinels.isEmpty()) {
      throw new IllegalArgumentException(
          "At least one sentinel must be specified for Sentinel mode");
    }
  }

  @Override
  public C build() {
    if (sentinelClientConfig == null) {
      // Sentinel connections use the legacy Jedis client which does not support RESP3
      // auto-negotiation, so the default config must opt out to avoid a spurious warning.
      sentinelClientConfig = DefaultJedisClientConfig.builder().serverDefaultProtocol().build();
    }

    return super.build();
  }

}

View on GitHub (pinned to 6dac31d4c2)