alibaba/spring-cloud-alibaba · error · IllegalArgumentException

RedisDataSource sentinel model，masterId can not be empty

Error message

RedisDataSource  sentinel model，masterId can not be empty

What it means

Thrown by RedisDataSourceProperties.preCheck when the masterId field is null or empty. The message references 'sentinel model' (note the full-width Chinese comma U+FF0C in the original source instead of ASCII comma). IMPORTANT GOTCHA: this check is UNCONDITIONAL — it always fires even when using standalone Redis (nodes not configured), not just in Redis Sentinel mode. The masterId is only actually used by the FactoryBean in the sentinel branch (when nodes is non-empty), but preCheck requires it regardless. This means standalone Redis users must also provide a masterId value even though it is unused.

Source

Thrown at spring-cloud-alibaba-starters/spring-cloud-alibaba-sentinel-datasource/src/main/java/com/alibaba/cloud/sentinel/datasource/config/RedisDataSourceProperties.java:98

	 * redis sentinel model.
	 */
	private @Nullable String masterId;

	@Override
	public void preCheck(String dataSourceName) {
		super.preCheck(dataSourceName);
		if (StringUtils.isEmpty(ruleKey)) {
			throw new IllegalArgumentException(
					"RedisDataSource  ruleKey can not be empty");
		}

		if (StringUtils.isEmpty(channel)) {
			throw new IllegalArgumentException(
					"RedisDataSource  channel can not be empty");
		}

		if (StringUtils.isEmpty(masterId)) {
			throw new IllegalArgumentException(
					"RedisDataSource  sentinel model，masterId can not be empty");
		}
	}

	public String getHost() {
		return host;
	}

	public void setHost(String host) {
		this.host = host;
	}

	public int getPort() {
		return port;
	}

	public void setPort(int port) {
		this.port = port;

View on GitHub (pinned to 115d590110)

Solutions

1. Add spring.cloud.sentinel.datasource.<name>.redis.masterId=<any-value> to your configuration — even for standalone Redis, a non-empty value satisfies the check (the value is unused by the FactoryBean in standalone mode).
2. If using Redis Sentinel mode, set masterId to the actual Sentinel master identifier (e.g., mymaster).
3. Be aware this is a known design quirk: the check does not distinguish standalone from sentinel mode.

Example fix

# before (broken — masterId missing in standalone Redis)
spring:
  cloud:
    sentinel:
      datasource:
        ds1:
          redis:
            host: redis.local
            ruleKey: sentinel:flow-rules
            channel: sentinel-rule-updates

# after (fixed — provide masterId even for standalone)
spring:
  cloud:
    sentinel:
      datasource:
        ds1:
          redis:
            host: redis.local
            ruleKey: sentinel:flow-rules
            channel: sentinel-rule-updates
            masterId: mymaster  # required by preCheck even in standalone mode

// IMPORTANT: masterId is required even for standalone Redis due to
// the unconditional check in RedisDataSourceProperties.preCheck()
String masterId = props.getRedis().getMasterId();
if (!StringUtils.hasText(masterId)) {
    // For standalone Redis, any non-empty value satisfies the check
    log.warn("RedisDataSource masterId is empty — setting placeholder for standalone mode");
    props.getRedis().setMasterId("standalone-placeholder");
}

When it happens

Trigger: Configuring ANY Sentinel datasource of type 'redis' (standalone or sentinel) without masterId set. Since the check at line 97 has no guard on whether nodes are configured, it fires for both standalone and sentinel deployments. The masterId field is @Nullable with no default.

Common situations: 1) Standalone Redis deployment (no sentinel nodes) — developer omits masterId thinking it is sentinel-only, but the unconditional check fires. 2) Redis Sentinel deployment where masterId was not provided. 3) Copy-paste from documentation that did not emphasize masterId as required for all Redis datasource configurations.

Related errors

• Invalid redis sentinel property {}
• RedisDataSource ruleKey can not be empty
• RedisDataSource channel can not be empty
• ConsulDataSource server-host is empty
• ConsulDataSource ruleKey can not be empty

AI-assisted analysis of alibaba/spring-cloud-alibaba@115d590110 (2026-08-14). Data as JSON: /api/errors/eca0a8b8a736b7c4. Report an issue: GitHub.