apache/shenyu · error · IllegalArgumentException

datacenter Id can't be greater than

Error message

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

What it means

Same Snowflake-style UUIDUtils constructor validates datacenterId within [0, MAX_DATACENTER_ID]. Values outside the range throw IllegalArgumentException 'datacenter Id can't be greater than %d or less than 0'.

Solutions

1. Use a datacenterId within 0..MAX_DATACENTER_ID (see the constant in UUIDUtils).
2. Clamp or modulo the configured value into range before constructing.
3. Validate datacenter-id configuration at startup with a clear error message.
4. Keep datacenter-id assignments coordinated across environments.

Example fix

// before
UUIDUtils.create(1, 999); // datacenterId out of range
// after
long dc = Math.floorMod(configuredDc, MAX_DATACENTER_ID + 1);
UUIDUtils.create(1, dc);

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

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

When it happens

Trigger: Constructing UUIDUtils with a datacenterId > MAX_DATACENTER_ID or < 0, e.g. from an out-of-range config value or faulty auto-assignment logic.

Common situations: Multi-datacenter deployments assigning ids beyond the configured maximum; config files with negative or oversized datacenter ids; refactored constants shrinking MAX_DATACENTER_ID while configs kept old values.

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

• worker 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/f80493396612ca2e. Report an issue: GitHub.

Appendix: source

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

    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;
    }

    private synchronized long nextId() {
        long timestamp = timeGen();
        if (timestamp < lastTimestamp) {

View on GitHub (pinned to 567142e072)