alibaba/spring-cloud-alibaba · error · IllegalStateException

serverAddr and path must not be null

Error message

serverAddr and path must not be null

What it means

Thrown by ZookeeperDataSourceFactoryBean.getObject() in the else branch (path mode) when serverAddr or path is null. The else branch is entered when either groupId or dataId is empty/not-provided, indicating the caller wants to use a raw Zookeeper path instead of groupId/dataId composition. In this mode, both serverAddr and path are required — if either is null, the IllegalStateException fires.

Source

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

	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() {
		return serverAddr;
	}

	public void setServerAddr(@Nullable String serverAddr) {
		this.serverAddr = serverAddr;
	}

View on GitHub (pinned to 115d590110)

Solutions

1. If using path mode, ensure both spring.cloud.sentinel.datasource.<name>.zk.server-addr and zk.path are set.
2. If you intended groupId/dataId mode, verify BOTH group-id and data-id are set — an empty value for either causes a silent switch to path mode.
3. Check for placeholder variables (${ZK_ADDR}, ${ZK_PATH}) that may resolve to null.

Example fix

# before (broken — groupId without dataId falls to path mode, no path set)
spring:
  cloud:
    sentinel:
      datasource:
        ds1:
          zk:
            server-addr: zk.local:2181
            group-id: sentinel
            # data-id omitted -> enters path mode, but path also missing

# after (fixed — option A: complete groupId/dataId mode)
spring:
  cloud:
    sentinel:
      datasource:
        ds1:
          zk:
            server-addr: zk.local:2181
            group-id: sentinel
            data-id: flow-rules

# after (fixed — option B: use path mode explicitly)
spring:
  cloud:
    sentinel:
      datasource:
        ds1:
          zk:
            server-addr: zk.local:2181
            path: /sentinel/flow-rules

// Detect mode ambiguity before FactoryBean.getObject()
// If using path mode, both serverAddr and path must be set
boolean groupIdMode = StringUtils.isNotEmpty(groupId) && StringUtils.isNotEmpty(dataId);
if (!groupIdMode) {
    // Path mode
    if (serverAddr == null) {
        throw new IllegalStateException(
            "serverAddr required for ZK path mode (groupId/dataId not both set)");
    }
    if (path == null) {
        throw new IllegalStateException(
            "path required for ZK path mode — or set BOTH groupId and dataId for groupId/dataId mode");
    }
}

When it happens

Trigger: Configuring a Sentinel datasource of type 'zk' where groupId or dataId is omitted (entering path mode) but either serverAddr or path is also missing. Common when a developer provides only groupId without dataId (falling to path mode unintentionally) and also forgets path.

Common situations: 1) Developer provides zk.group-id but not zk.data-id (falls to path mode) and does not provide zk.path. 2) serverAddr is explicitly cleared while using path mode. 3) Programmatic FactoryBean with path set but serverAddr omitted, or vice versa. 4) Intended to use groupId/dataId mode but one was empty, silently switching to path mode without the required path.

Related errors

• serverAddr, groupId, and dataId 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/8b50a9b1f87daf69. Report an issue: GitHub.