alibaba/Sentinel · error · IllegalArgumentException

Cold factor should be larger than 1

Error message

Cold factor should be larger than 1

What it means

WarmUpController implements the traffic-shaping warm-up (cold-start) flow control based on Guava's SmoothWarmingUp model. Its math divides by (coldFactor - 1) when computing warningToken, so coldFactor <= 1 would divide by zero and destroy the ramp curve; the constructor rejects it with IllegalArgumentException.

Source

Thrown at sentinel-core/src/main/java/com/alibaba/csp/sentinel/slots/block/flow/controller/WarmUpController.java:86

    protected int warningToken = 0;
    private int maxToken;
    protected double slope;

    protected AtomicLong storedTokens = new AtomicLong(0);
    protected AtomicLong lastFilledTime = new AtomicLong(0);

    public WarmUpController(double count, int warmUpPeriodInSec, int coldFactor) {
        construct(count, warmUpPeriodInSec, coldFactor);
    }

    public WarmUpController(double count, int warmUpPeriodInSec) {
        construct(count, warmUpPeriodInSec, 3);
    }

    private void construct(double count, int warmUpPeriodInSec, int coldFactor) {

        if (coldFactor <= 1) {
            throw new IllegalArgumentException("Cold factor should be larger than 1");
        }

        this.count = count;

        this.coldFactor = coldFactor;

        // thresholdPermits = 0.5 * warmupPeriod / stableInterval.
        // warningToken = 100;
        warningToken = (int)(warmUpPeriodInSec * count) / (coldFactor - 1);
        // / maxPermits = thresholdPermits + 2 * warmupPeriod /
        // (stableInterval + coldInterval)
        // maxToken = 200
        maxToken = warningToken + (int)(2 * warmUpPeriodInSec * count / (1.0 + coldFactor));

        // slope
        // slope = (coldIntervalMicros - stableIntervalMicros) / (maxPermits
        // - thresholdPermits);
        slope = (coldFactor - 1.0) / count / (maxToken - warningToken);

View on GitHub (pinned to a3f40ba8e9)

Solutions

1. Set coldFactor to a value > 1; the default and recommended value is 3.
2. If you actually want no warm-up, do not use WarmUpController — configure the FlowRule with the default (rate limiter / straight) controller instead of warm-up grade.
3. Check FlowRule.controlBehavior / warmUpColdFactor values coming from dashboard or dynamic config and clamp to >= 2.

Example fix

// before
new WarmUpController(100, 10, 1);

// after
new WarmUpController(100, 10, 3);
// or, for no warm-up at all, use the default controller:
new RateLimiterController(100, 10);

int coldFactor = configuredColdFactor <= 1 ? 3 : configuredColdFactor;
TrafficShapingController c = new WarmUpController(count, warmUpPeriodSec, coldFactor);

When it happens

Trigger: new WarmUpController(count, warmUpPeriodInSec, coldFactor) with coldFactor 1 or less, e.g. new WarmUpController(100, 10, 1). Note the two-arg constructor always uses the safe default coldFactor=3.

Common situations: User configuration sets coldFactor=1 believing 1 means 'no warm-up', or a FlowRule loaded with warmUpGrade and controllerArguments containing 1. Version note: older Sentinel (<1.4) allowed coldFactor=1 to bypass warm-up; newer code requires > 1.

Related errors

• Null value
• keys empty or null: ${keys}
• keys empty or null
• Max entry count should be at least 1:
• Invalid second interval (cannot divide by 60):

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