What causes "worker Id can't be greater than %d or less than 0" in shuzheng/zheng?

Assign each instance a workerId between 0 and 31 (inclusive) in configuration/environment.

shuzheng/zheng · error · IllegalArgumentException

worker Id can't be greater than %d or less than 0

Error message

worker Id can't be greater than %d or less than 0

What it means

SnowflakeIdWorker's constructor validates the workerId argument against maxWorkerId (31, since 5 bits are used for worker id) and throws IllegalArgumentException when workerId > 31 or workerId < 0. This guarantees worker-id bits never overflow into other bit fields of the generated 64-bit snowflake id.

Source

Thrown at zheng-common/src/main/java/com/zheng/common/util/key/SnowflakeIdWorker.java:97

	 */
	private long sequence = 0L;

	/**
	 * 上次生成ID的时间截
	 */
	private long lastTimestamp = -1L;

	//==============================Constructors=====================================

	/**
	 * 构造函数
	 *
	 * @param workerId     工作ID (0~31)
	 * @param datacenterId 数据中心ID (0~31)
	 */
	public SnowflakeIdWorker(long workerId, long datacenterId) {
		if (workerId > maxWorkerId || workerId < 0) {
			throw new IllegalArgumentException(String.format("worker Id can't be greater than %d or less than 0", maxWorkerId));
		}
		if (datacenterId > maxDatacenterId || datacenterId < 0) {
			throw new IllegalArgumentException(String.format("datacenter Id can't be greater than %d or less than 0", maxDatacenterId));
		}
		this.workerId = workerId;
		this.datacenterId = datacenterId;
	}

	// ==============================Methods==========================================

	/**
	 * 获得下一个ID (该方法是线程安全的)
	 *
	 * @return SnowflakeId
	 */
	public synchronized long nextId() {
		long timestamp = timeGen();

View on GitHub (pinned to 7005c0a775)

Solutions

Assign each instance a workerId between 0 and 31 (inclusive) in configuration/environment.
If more than 32 workers are needed, also differentiate datacenterId (0..31) so the pair (datacenterId, workerId) is unique.
Clamp or modulo-validate the workerId at config load time and fail fast with a clear message.
Generate workerId from a coordination service (zookeeper/redis) ensuring uniqueness within the valid range.

Example fix

// before
long workerId = Long.parseLong(env.get("WORKER_ID")); // e.g. 55
SnowflakeIdWorker w = new SnowflakeIdWorker(workerId, 1);
// after
long workerId = Long.parseLong(env.get("WORKER_ID")) % 32;
if (workerId < 0) workerId += 32;
SnowflakeIdWorker w = new SnowflakeIdWorker(workerId, 1);

Defensive patterns

Strategy: validation

Validate before calling

if (workerId < 0 || workerId > 31) {
    throw new IllegalArgumentException("workerId must be in [0,31], got " + workerId);
}
new SnowflakeIdWorker(workerId, datacenterId);

Type guard

boolean isValidWorkerId(long id) {
    return id >= 0 && id <= 31;
}

Try / catch

try {
    idWorker = new SnowflakeIdWorker(workerId, dcId);
} catch (IllegalArgumentException e) {
    log.error("Invalid snowflake node config: {}", e.getMessage());
    throw new IllegalStateException("Fix WORKER_ID config", e);
}

Prevention

Assign unique workerIds 0..31 per node via config management or a coordinator service.
Validate workerId at application startup before any id generation.
Use (datacenterId, workerId) pairs to scale beyond 32 nodes.
Fail fast on negative values from missing environment variables (parse with explicit defaults).

When it happens

Trigger: new SnowflakeIdWorker(workerId, datacenterId) with workerId outside the inclusive range 0..31, e.g. reading an unconfigured/zero-value config field or computing workerId from a host index >= 32.

Common situations: Deploying more than 32 instances sharing a workerId source; env variable missing so a default like -1 or 0-configured value out of range is used; refactoring changed the number of allowed bits but not the callers.

Related errors

AI-assisted analysis of shuzheng/zheng@7005c0a775 (2026-09-04). Data as JSON: /api/errors/3aa87dc3a83abc41. Report an issue: GitHub.