alibaba/spring-cloud-alibaba · error · IllegalArgumentException

ConsulDataSource ruleKey can not be empty

Error message

ConsulDataSource ruleKey can not be empty

What it means

Thrown by ConsulDataSourceProperties.preCheck when the ruleKey field is null or empty. The ruleKey identifies the Consul KV key that holds the Sentinel rule data. This check fires after the host check passes, ensuring both required Consul-specific properties are present before datasource creation.

Source

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

	private @Nullable String token;

	/**
	 * data key in Redis.
	 */
	private @Nullable String ruleKey;

	/**
	 * Request of query will hang until timeout (in second) or get updated value.
	 */
	private int waitTimeoutInSecond = 1;

	@Override
	public void preCheck(String dataSourceName) {
		if (StringUtils.isEmpty(host)) {
			throw new IllegalArgumentException("ConsulDataSource server-host is empty");
		}
		if (StringUtils.isEmpty(ruleKey)) {
			throw new IllegalArgumentException(
					"ConsulDataSource ruleKey can not be empty");
		}
	}

	public @Nullable String getHost() {
		return host;
	}

	public void setHost(@Nullable 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>.consul.ruleKey=<consul-kv-key> to your configuration.
2. Verify the ruleKey value matches the actual key path in your Consul KV store.
3. Ensure the ruleKey is not an empty string (StringUtils.isEmpty catches both null and "").

Example fix

# before (broken — ruleKey missing)
spring:
  cloud:
    sentinel:
      datasource:
        ds1:
          consul:
            host: consul.local

# after (fixed)
spring:
  cloud:
    sentinel:
      datasource:
        ds1:
          consul:
            host: consul.local
            ruleKey: sentinel/sentinel-flow-rules

// Ensure ruleKey is set before datasource initialization
// In YAML: spring.cloud.sentinel.datasource.<name>.consul.ruleKey must be non-empty
// Programmatic check:
String ruleKey = props.getConsul().getRuleKey();
if (!StringUtils.hasText(ruleKey)) {
    throw new IllegalArgumentException("ConsulDataSource ruleKey is required");
}

When it happens

Trigger: Configuring a Sentinel datasource of type 'consul' with a host set but no ruleKey. The ruleKey field is @Nullable with no default, so omitting spring.cloud.sentinel.datasource.<name>.consul.ruleKey causes StringUtils.isEmpty(ruleKey) to be true.

Common situations: 1) Developer provides consul.host but forgets ruleKey. 2) The Consul KV key name was renamed in the Consul server but not updated in application config. 3) Copy-paste error where ruleKey was left as an empty string or placeholder.

Related errors

• ConsulDataSource server-host is empty
• [Sentinel Starter] DataSource {} file cannot be null
• RedisDataSource ruleKey can not be empty
• RedisDataSource channel can not be empty
• RedisDataSource sentinel model，masterId can not be empty

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