alibaba/nacos · critical · IllegalArgumentException

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

Error message

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

What it means

Thrown by SnowFlowerIdGenerator.initialize(workerId) when the worker id is outside the allowed range [0, 1024]. WORKER_ID_MAX_VALUE is 1024. It is an IllegalArgumentException raised during init() (called at bean construction), so it prevents server startup.

Source

Thrown at core/src/main/java/com/alibaba/nacos/core/distributed/id/SnowFlowerIdGenerator.java:153

    
    @Override
    public Map<Object, Object> info() {
        Map<Object, Object> info = new HashMap<>(4);
        info.put("currentId", currentId);
        info.put("workerId", workerId);
        return info;
    }
    
    // ==============================Constructors=====================================
    
    /**
     * init
     *
     * @param workerId worker id (0~1024)
     */
    public void initialize(long workerId) {
        if (workerId > WORKER_ID_MAX_VALUE || workerId < 0) {
            throw new IllegalArgumentException(
                String.format(
                    "worker Id can't be greater than %d or less than 0, current workId %d",
                    WORKER_ID_MAX_VALUE, workerId));
        }
        this.workerId = workerId;
    }
    
    /**
     * Block to the next millisecond until a new timestamp is obtained
     *
     * @param lastTimestamp The time intercept of the last ID generated
     * @return Current timestamp
     */
    private long waitUntilNextTime(long lastTimestamp) {
        long time;
        time = currentTimeMillis();
        while (time <= lastTimestamp) {
            time = currentTimeMillis();

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Set nacos.core.snowflake.worker-id to a value in [0, 1024], unique per cluster node.
2. If you omit the property, Nacos derives a worker id from the IP — ensure that derivation stays in range across all nodes.
3. In large clusters (>1024 nodes), you cannot use the built-in snowflake worker-id space as-is; coordinate a sharding scheme.

Example fix

// before
-Dnacos.core.snowflake.worker-id=5000

// after
-Dnacos.core.snowflake.worker-id=5

final long MAX = 1024L;
if (workerId < 0 || workerId > MAX) {
    throw new IllegalArgumentException("workerId must be in [0," + MAX + "]");
}

try {
    snowFlowerIdGenerator.initialize(workerId);
} catch (IllegalArgumentException e) {
    // choose a valid worker-id in [0,1024] and retry
}

When it happens

Trigger: Explicitly setting nacos.core.snowflake.worker-id to a value < 0 or > 1024. When unset, the IP-derived worker id could in theory also exceed the range, but the explicit override is the usual cause.

Common situations: An operator sets a worker-id from a node-indexing scheme that exceeds 1024; negative value typo; multiple nodes accidentally given the same high id; copying a config across environments with a stale large value.

Related errors

• Cannot get LocalHost InetAddress, please check your network!
• [http-client] invalid connect timeout:{}
• Illegal Raft system parameters => ReadOnlyOption : [{val}],
• serverList is empty,please check configuration
• 400

AI-assisted analysis of alibaba/nacos@9b989acdf1 (2026-08-14). Data as JSON: /api/errors/17780ae464f9c08f. Report an issue: GitHub.