alibaba/spring-cloud-alibaba · error · IllegalStateException

serverAddr, groupId, and dataId must not be null

Error message

serverAddr, groupId, and dataId must not be null

What it means

Thrown by ZookeeperDataSourceFactoryBean.getObject() in the groupId/dataId branch when serverAddr is null. IMPORTANT: the outer condition checks isNotEmpty(groupId) && isNotEmpty(dataId), which guarantees both are non-null and non-blank. Therefore the inner check 'groupId == null || dataId == null' is dead code — this error can ONLY fire when serverAddr is null while groupId and dataId are both provided. The message lists all three for documentation purposes but the practical trigger is a missing serverAddr.

Source

Thrown at spring-cloud-alibaba-starters/spring-cloud-alibaba-sentinel-datasource/src/main/java/com/alibaba/cloud/sentinel/datasource/factorybean/ZookeeperDataSourceFactoryBean.java:49

 */
public class ZookeeperDataSourceFactoryBean implements FactoryBean<ZookeeperDataSource> {

	private @Nullable String serverAddr;

	private @Nullable String path;

	private @Nullable String groupId;

	private @Nullable String dataId;

	private @Nullable Converter converter;

	@Override
	public ZookeeperDataSource getObject() throws Exception {
		if (StringUtils.isNotEmpty(groupId) && StringUtils.isNotEmpty(dataId)) {
			// the path will be /{groupId}/{dataId}
			if (serverAddr == null || groupId == null || dataId == null) {
				throw new IllegalStateException("serverAddr, groupId, and dataId must not be null");
			}
			return new ZookeeperDataSource(serverAddr, groupId, dataId, converter);
		}
		else {
			// using path directly
			if (serverAddr == null || path == null) {
				throw new IllegalStateException("serverAddr and path must not be null");
			}
			return new ZookeeperDataSource(serverAddr, path, converter);
		}
	}

	@Override
	public Class<?> getObjectType() {
		return ZookeeperDataSource.class;
	}

	public @Nullable String getServerAddr() {

View on GitHub (pinned to 115d590110)

Solutions

1. Set spring.cloud.sentinel.datasource.<name>.zk.server-addr=<zk-host:port> to a valid Zookeeper address.
2. Verify that ZookeeperDataSourceProperties.serverAddr (which defaults to 'localhost:2181') is not being overridden to null or empty by a profile or programmatic config.
3. If constructing the FactoryBean programmatically, call setServerAddr() before getObject().

Example fix

# before (broken — serverAddr missing)
spring:
  cloud:
    sentinel:
      datasource:
        ds1:
          zk:
            group-id: sentinel
            data-id: flow-rules

# after (fixed)
spring:
  cloud:
    sentinel:
      datasource:
        ds1:
          zk:
            server-addr: zk.local:2181
            group-id: sentinel
            data-id: flow-rules

// Validate ZookeeperDataSourceFactoryBean properties before getObject()
ZookeeperDataSourceFactoryBean fb = new ZookeeperDataSourceFactoryBean();
if (StringUtils.isNotEmpty(groupId) && StringUtils.isNotEmpty(dataId)) {
    if (serverAddr == null) {
        throw new IllegalStateException("serverAddr is required when using groupId/dataId mode");
    }
} else {
    if (serverAddr == null || path == null) {
        throw new IllegalStateException("serverAddr and path are required in path mode");
    }
}
fb.setServerAddr(serverAddr);
fb.setGroupId(groupId);
fb.setDataId(dataId);
fb.setConverter(converter);
fb.getObject();

When it happens

Trigger: Configuring a Sentinel datasource of type 'zk' with groupId and dataId both set (non-empty) but serverAddr not provided (null). The FactoryBean enters the groupId/dataId branch, and the serverAddr null check at line 48 triggers.

Common situations: 1) Developer provides zk.group-id and zk.data-id but forgets zk.server-addr. 2) serverAddr placeholder (${ZK_ADDR}) is not set in the environment and resolves to null (note: ZookeeperDataSourceProperties defaults serverAddr to 'localhost:2181', but if the FactoryBean is wired directly or the property is explicitly cleared, it can be null). 3) Programmatic FactoryBean creation with groupId/dataId set but serverAddr omitted.

Related errors

• serverAddr and path must not be null
• ZookeeperDataSource server-addr is empty
• namespaceName, flowRulesKey, and defaultFlowRuleValue must n
• Invalid redis sentinel property {}
• ConsulDataSource server-host is empty

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