redis/jedis · error · IllegalArgumentException

Master name is required for Sentinel mode

Error message

Master name is required for Sentinel mode

What it means

Sentinel mode requires the logical name of the master monitored by the Sentinel quorum; the client uses it to ask sentinels for the current master address. SentinelClientBuilder.validateSpecificConfiguration() throws this IllegalArgumentException when masterName is null or blank (null/whitespace-only) at build() time.

Solutions

1. Call .masterName("mymaster") with the exact master name configured on your sentinels (verify with SENTINEL masters).
2. Fail fast at config load if the master-name property is missing/blank instead of passing it to the builder.
3. Trim the value and check !name.isBlank() (or equivalent for JDK 8) before building.

Example fix

// before
RedisSentinelClient client = RedisSentinelClient.builder()
    .sentinels(sentinels)
    .build(); // throws: no masterName
// after
RedisSentinelClient client = RedisSentinelClient.builder()
    .masterName("mymaster")
    .sentinels(sentinels)
    .build();

if (masterName == null || masterName.trim().isEmpty()) {
  throw new IllegalArgumentException("sentinel masterName is required");
}

When it happens

Trigger: Building a RedisSentinelClient without calling .masterName(...), or with .masterName(" ") / .masterName("") / a null value sourced from configuration.

Common situations: Missing or misnamed key in properties/env (e.g. redis.master vs redis.masterName) resolving to null; YAML indentation issues yielding empty string; copying a standalone example into a Sentinel deployment without adding the master name.

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

• At least one sentinel must be specified for Sentinel mode
• HostAndPort is required when no socketFactory is provided
• Client-side caching is only supported with RESP3.
• At least one cluster node must be specified for cluster mode
• Max attempts must be positive for cluster mode

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

Appendix: source

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

  }

  @Override
  protected SentinelClientBuilder<C> self() {
    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)