{"record":{"id":"002a9a791c47c9a9","repo":"alibaba/Sentinel","slug":"cold-factor-should-be-larger-than-1","errorCode":null,"errorMessage":"Cold factor should be larger than 1","messagePattern":"Cold factor should be larger than 1","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"sentinel-core/src/main/java/com/alibaba/csp/sentinel/slots/block/flow/controller/WarmUpController.java","lineNumber":86,"sourceCode":"    protected int warningToken = 0;\n    private int maxToken;\n    protected double slope;\n\n    protected AtomicLong storedTokens = new AtomicLong(0);\n    protected AtomicLong lastFilledTime = new AtomicLong(0);\n\n    public WarmUpController(double count, int warmUpPeriodInSec, int coldFactor) {\n        construct(count, warmUpPeriodInSec, coldFactor);\n    }\n\n    public WarmUpController(double count, int warmUpPeriodInSec) {\n        construct(count, warmUpPeriodInSec, 3);\n    }\n\n    private void construct(double count, int warmUpPeriodInSec, int coldFactor) {\n\n        if (coldFactor <= 1) {\n            throw new IllegalArgumentException(\"Cold factor should be larger than 1\");\n        }\n\n        this.count = count;\n\n        this.coldFactor = coldFactor;\n\n        // thresholdPermits = 0.5 * warmupPeriod / stableInterval.\n        // warningToken = 100;\n        warningToken = (int)(warmUpPeriodInSec * count) / (coldFactor - 1);\n        // / maxPermits = thresholdPermits + 2 * warmupPeriod /\n        // (stableInterval + coldInterval)\n        // maxToken = 200\n        maxToken = warningToken + (int)(2 * warmUpPeriodInSec * count / (1.0 + coldFactor));\n\n        // slope\n        // slope = (coldIntervalMicros - stableIntervalMicros) / (maxPermits\n        // - thresholdPermits);\n        slope = (coldFactor - 1.0) / count / (maxToken - warningToken);","sourceCodeStart":68,"sourceCodeEnd":104,"githubUrl":"https://github.com/alibaba/Sentinel/blob/a3f40ba8e900c8489bd520274739f17235a7721c/sentinel-core/src/main/java/com/alibaba/csp/sentinel/slots/block/flow/controller/WarmUpController.java#L68-L104","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Set coldFactor to a value > 1; the default and recommended value is 3.","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.","Check FlowRule.controlBehavior / warmUpColdFactor values coming from dashboard or dynamic config and clamp to >= 2."],"exampleFix":"// before\nnew WarmUpController(100, 10, 1);\n\n// after\nnew WarmUpController(100, 10, 3);\n// or, for no warm-up at all, use the default controller:\nnew RateLimiterController(100, 10);","handlingStrategy":"validation","validationCode":"int coldFactor = configuredColdFactor <= 1 ? 3 : configuredColdFactor;\nTrafficShapingController c = new WarmUpController(count, warmUpPeriodSec, coldFactor);","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Treat coldFactor=1 in config as 'no warm-up' and switch controlBehavior to the default controller, not WarmUpController.","Clamp user-supplied coldFactor to >= 2 at the config boundary."],"tags":["sentinel","flow-control","warm-up","validation"],"backgroundTag":null,"analyzedSha":"a3f40ba8e900c8489bd520274739f17235a7721c","analyzedAt":"2026-08-14T11:10:30.678Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}