alibaba/Sentinel · error · IllegalArgumentException

intervalMillis should be at least 1000, but given:

Error message

intervalMillis should be at least 1000, but given: 

What it means

TokenBucket requires intervalMillis >= 1000 (1 second). The refill logic resets tokens only when now > nextUpdate, so sub-second intervals would break the second-aligned update math (nextUpdate is computed as currentTimeMillis / 1000 * 1000 + intervalMillis). Anything below 1000ms is rejected with IllegalArgumentException.

Source

Thrown at sentinel-core/src/main/java/com/alibaba/csp/sentinel/eagleeye/TokenBucket.java:35

import java.util.concurrent.atomic.AtomicLong;

class TokenBucket {

    private final long maxTokens;

    private final long intervalMillis;

    private volatile long nextUpdate;

    private AtomicLong tokens;

    public TokenBucket(long maxTokens, long intervalMillis) {
        if (maxTokens <= 0) {
            throw new IllegalArgumentException("maxTokens should > 0, but given: " + maxTokens);
        }
        if (intervalMillis < 1000) {
            throw new IllegalArgumentException("intervalMillis should be at least 1000, but given: " + intervalMillis);
        }
        this.maxTokens = maxTokens;
        this.intervalMillis = intervalMillis;
        this.nextUpdate = System.currentTimeMillis() / 1000 * 1000 + intervalMillis;
        this.tokens = new AtomicLong(maxTokens);
    }

    public boolean accept(long now) {
        long currTokens;
        if (now > nextUpdate) {
            currTokens = tokens.get();
            if (tokens.compareAndSet(currTokens, maxTokens)) {
                nextUpdate = System.currentTimeMillis() / 1000 * 1000 + intervalMillis;
            }
        }

        do {
            currTokens = tokens.get();

View on GitHub (pinned to a3f40ba8e9)

Solutions

1. Pass an interval of at least 1000 milliseconds, e.g. 1000 or 60000.
2. Verify the unit of the value feeding intervalMillis; convert seconds to milliseconds if needed.
3. If sub-second granularity is required, TokenBucket cannot support it — use a different rate-limiting utility.

Example fix

// before
new TokenBucket(10, 500); // wanted 500ms

// after
new TokenBucket(10, 1000); // minimum supported interval

long interval = requestedIntervalMs < 1000 ? 1000 : requestedIntervalMs; // clamp or reject
if (requestedIntervalMs < 1000) {
    throw new ConfigurationException("interval must be >= 1000ms");
}
TokenBucket bucket = new TokenBucket(maxTokens, interval);

When it happens

Trigger: new TokenBucket(maxTokens, intervalMillis) with intervalMillis < 1000, e.g. new TokenBucket(10, 500) or passing seconds instead of milliseconds via a typo'd constant.

Common situations: Confusing units (passing 1 meaning 1 second instead of 1000ms), or copying a sub-second refresh interval from another rate limiter's config into EagleEye's TokenBucket.

Related errors

• maxTokens should > 0, but given:
• ${param}
• ${name} is null
• keys empty or null: ${keys}
• keys empty or null

AI-assisted analysis of alibaba/Sentinel@a3f40ba8e9 (2026-08-14). Data as JSON: /api/errors/afd0c05bf04c99bd. Report an issue: GitHub.