shuzheng/zheng · error · IllegalArgumentException

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

Error message

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

What it means

Same validation as workerId but for datacenterId: the constructor throws IllegalArgumentException when datacenterId > maxDatacenterId (31) or < 0. The 5-bit datacenter field must fit in the snowflake id layout.

Source

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

	/**
	 * 上次生成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();

		//如果当前时间小于上一次ID生成的时间戳，说明系统时钟回退过这个时候应当抛出异常
		if (timestamp < lastTimestamp) {
			throw new RuntimeException(

View on GitHub (pinned to 7005c0a775)

Solutions

1. Set datacenterId to a value in 0..31 (inclusive).
2. Remap datacenter numbers larger than 31 down to the valid range, combining with a distinct workerId to keep uniqueness.
3. Validate the value where it is read from config and fail early with a descriptive message.

Example fix

// before
SnowflakeIdWorker w = new SnowflakeIdWorker(1, 40); // datacenterId=40 out of range
// after
SnowflakeIdWorker w = new SnowflakeIdWorker(1, 40 % 32); // or renumber DC to 0..31

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

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

try {
    idWorker = new SnowflakeIdWorker(workerId, datacenterId);
} catch (IllegalArgumentException e) {
    log.error("Invalid datacenter id: {}", e.getMessage());
    throw new IllegalStateException("Fix DATACENTER_ID config", e);
}

When it happens

Trigger: new SnowflakeIdWorker(workerId, datacenterId) with datacenterId outside 0..31, e.g. a datacenter number of 32+ in a multi-DC deployment or a negative/unset value.

Common situations: Multi-datacenter deployment where DC numbering starts at 1 but exceeds 31; misconfigured environment variable; copy-paste of workerId into datacenterId slot with an out-of-range value.

Related errors

• worker Id can't be greater than %d or less than 0
• Clock moved backwards. Refusing to generate id for %d milli
• 未注册的系统:%s

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