{"record":{"id":"38145255d8b24f4b","repo":"apache/incubator-seata","slug":"worker-id-can-t-be-greater-than-d-or-less-than-0","errorCode":null,"errorMessage":"worker Id can't be greater than %d or less than 0","messagePattern":"worker Id can't be greater than (.+?) or less than 0","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"common/src/main/java/org/apache/seata/common/util/IdWorker.java","lineNumber":101,"sourceCode":"     * init first timestamp and sequence immediately\n     */\n    private void initTimestampAndSequence() {\n        long timestamp = getNewestTimestamp();\n        long timestampWithSequence = timestamp << sequenceBits;\n        this.timestampAndSequence = new AtomicLong(timestampWithSequence);\n    }\n\n    /**\n     * init workerId\n     * @param workerId if null, then auto generate one\n     */\n    private void initWorkerId(Long workerId) {\n        if (workerId == null) {\n            workerId = generateWorkerId();\n        }\n        if (workerId > maxWorkerId || workerId < 0) {\n            String message = String.format(\"worker Id can't be greater than %d or less than 0\", maxWorkerId);\n            throw new IllegalArgumentException(message);\n        }\n        this.workerId = workerId << (timestampBits + sequenceBits);\n    }\n\n    /**\n     * get next UUID(base on snowflake algorithm), which look like:\n     * highest 1 bit: always 0\n     * next   10 bit: workerId\n     * next   41 bit: timestamp\n     * lowest 12 bit: sequence\n     * @return UUID\n     */\n    public long nextId() {\n        waitIfNecessary();\n        long next = timestampAndSequence.incrementAndGet();\n        long timestampWithSequence = next & timestampAndSequenceMask;\n        return workerId | timestampWithSequence;\n    }","sourceCodeStart":83,"sourceCodeEnd":119,"githubUrl":"https://github.com/apache/incubator-seata/blob/e01f97c6db397165050caa6764020410c2c8199a/common/src/main/java/org/apache/seata/common/util/IdWorker.java#L83-L119","documentation":"IdWorker is Seata's snowflake-based ID generator. Its workerId occupies 10 bits (maxWorkerId, typically 1023), and initWorkerId validates the configured/generated worker id against that range. This IllegalArgumentException fires when workerId is negative or exceeds maxWorkerId, because shifting an out-of-range id would corrupt the generated UUID layout.","triggerScenarios":"Constructing IdWorker with an explicit workerId (e.g. new IdWorker(1024) or new IdWorker(-1)), or setting idWorkerId via configuration to a value above 1023 (or negative). If workerId is null one is auto-generated from MAC or randomly, which stays in range.","commonSituations":"A node index / pod ordinal (e.g. Kubernetes StatefulSet ordinal up to thousands) is fed directly as workerId; or an operator sets a worker id in a distributed deployment where the value was chosen without accounting for the 10-bit limit.","solutions":["Set workerId to a value in [0, 1023]","Derive workerId from a stable small identifier such as the low 10 bits of a MAC hash or pod ordinal modulo 1024","Pass null to let IdWorker auto-generate a workerId (MAC-based, falling back to random)"],"exampleFix":"// before\nIdWorker worker = new IdWorker(5000); // > 1023, throws\n\n// after\nIdWorker worker = new IdWorker(5000 % 1024); // or pass null for auto-generation","handlingStrategy":"validation","validationCode":"long MAX = (1L << 10) - 1; // 1023, matches worker id bits\nif (workerId == null || workerId < 0 || workerId > 1023) workerId = Math.floorMod(podOrdinal, 1024);\nIdWorker w = new IdWorker(workerId);","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Assign worker ids from a bounded pool [0,1023]","Never feed raw pod ordinals or node indexes without modulo","Record the chosen workerId in logs to detect collisions"],"tags":["id-generation","snowflake","configuration","seata-common"],"backgroundTag":null,"analyzedSha":"e01f97c6db397165050caa6764020410c2c8199a","analyzedAt":"2026-08-14T10:23:53.097Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}