apache/shenyu · error · IllegalArgumentException

worker Id can't be greater than

Error message

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

What it means

UUIDUtils implements a Snowflake-style ID generator. Its constructor validates that workerId is within [0, MAX_WORKER_ID]; out-of-range values throw IllegalArgumentException 'worker Id can't be greater than %d or less than 0' with MAX_WORKER_ID formatted in.

Solutions

1. Pass a workerId within 0..MAX_WORKER_ID (check the constant value in UUIDUtils).
2. Compute workerId via modulo: workerId % (MAX_WORKER_ID + 1).
3. Ensure configured worker-id properties are non-negative integers within range before constructing.
4. Use distinct, validated worker ids per instance to also avoid duplicate-id issues.

Example fix

// before
long workerId = Long.parseLong(env.get("WORKER_ID")); // e.g. -3
// after
long workerId = Long.parseLong(env.getOrDefault("WORKER_ID", "0")) % (MAX_WORKER_ID + 1);
if (workerId < 0) { workerId += MAX_WORKER_ID + 1; }

if (workerId < 0 || workerId > MAX_WORKER_ID) throw new IllegalArgumentException("workerId must be in [0," + MAX_WORKER_ID + "]");

try { idGen = new UUIDUtils(workerId, dcId, epoch); } catch (IllegalArgumentException e) { LOG.error("bad worker id", e); idGen = new UUIDUtils(0, dcId, epoch); }

When it happens

Trigger: Constructing UUIDUtils (private) with a workerId > MAX_WORKER_ID or < 0 — typically when the random/generated worker id computation or a manually supplied id from config violates the bound.

Common situations: Deploying many instances where auto-assigned worker ids collide and custom id logic overflows the range; copying Snowflake code with different MAX_WORKER_ID; config file supplying negative worker id.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• datacenter Id can't be greater than
• Clock moved backwards. Refusing to generate id for
• dynamic: result.getMessage() from…
• Max response body size must not be negative
• The configuration shenyu.discovery.type in xml/yml cannot…

AI-assisted analysis of apache/shenyu@567142e072 (2026-09-12). Data as JSON: /api/errors/56afd8e246e082b7. Report an issue: GitHub.

Appendix: source

Thrown at shenyu-common/src/main/java/org/apache/shenyu/common/utils/UUIDUtils.java:65

    private static final UUIDUtils ID_WORKER_UTILS = new UUIDUtils();

    private final long workerId;

    private final long datacenterId;

    private final long idepoch;

    private long sequence = '0';

    private long lastTimestamp = -1L;

    private UUIDUtils() {
        this(RANDOM.nextInt((int) MAX_WORKER_ID), RANDOM.nextInt((int) MAX_DATACENTER_ID), 1288834974657L);
    }

    private UUIDUtils(final long workerId, final long datacenterId, final long idepoch) {
        if (workerId > MAX_WORKER_ID || workerId < 0) {
            throw new IllegalArgumentException(String.format("worker Id can't be greater than %d or less than 0", MAX_WORKER_ID));
        }
        if (datacenterId > MAX_DATACENTER_ID || datacenterId < 0) {
            throw new IllegalArgumentException(String.format("datacenter Id can't be greater than %d or less than 0", MAX_DATACENTER_ID));
        }
        this.workerId = workerId;
        this.datacenterId = datacenterId;
        this.idepoch = idepoch;
    }

    /**
     * Gets instance.
     *
     * @return the instance
     */
    public static UUIDUtils getInstance() {
        return ID_WORKER_UTILS;
    }

View on GitHub (pinned to 567142e072)