{"record":{"id":"754d52565e277b20","repo":"apache/beam","slug":"overloadratio-must-be-greater-than-1-0","errorCode":null,"errorMessage":"overloadRatio must be greater than 1.0","messagePattern":"overloadRatio must be greater than 1\\.0","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"sdks/java/io/components/src/main/java/org/apache/beam/sdk/io/components/throttling/AdaptiveThrottler.java","lineNumber":60,"sourceCode":"  private final MovingFunction successfulRequests;\n  private final double overloadRatio;\n  private final Random random;\n\n  /**\n   * Initializes AdaptiveThrottler.\n   *\n   * @param samplePeriodMs length of history to consider, in ms, to set throttling.\n   * @param sampleUpdateMs granularity of time buckets that we store data in, in ms.\n   * @param overloadRatio the target ratio between requests sent and successful requests.\n   */\n  public AdaptiveThrottler(long samplePeriodMs, long sampleUpdateMs, double overloadRatio) {\n    this(samplePeriodMs, sampleUpdateMs, overloadRatio, new Random());\n  }\n\n  // visible for testing\n  AdaptiveThrottler(long samplePeriodMs, long sampleUpdateMs, double overloadRatio, Random random) {\n    if (overloadRatio <= 1.0) {\n      throw new IllegalArgumentException(\"overloadRatio must be greater than 1.0\");\n    }\n    this.allRequests = new MovingFunction(samplePeriodMs, sampleUpdateMs, 1, 1, Sum.ofLongs());\n    this.successfulRequests =\n        new MovingFunction(samplePeriodMs, sampleUpdateMs, 1, 1, Sum.ofLongs());\n    this.overloadRatio = overloadRatio;\n    this.random = random;\n  }\n\n  protected double throttlingProbability(long nowMsSinceEpoch) {\n    long allReqs = allRequests.get(nowMsSinceEpoch);\n    if (!allRequests.isSignificant()) {\n      return 0.0;\n    }\n    long successfulReqs = successfulRequests.get(nowMsSinceEpoch);\n    double prob = (allReqs - overloadRatio * successfulReqs) / (allReqs + MIN_REQUESTS);\n    return Math.max(0.0, prob);\n  }\n","sourceCodeStart":42,"sourceCodeEnd":78,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/io/components/src/main/java/org/apache/beam/sdk/io/components/throttling/AdaptiveThrottler.java#L42-L78","documentation":"AdaptiveThrottler's constructor rejects overloadRatio values <= 1.0 with an IllegalArgumentException. The overload ratio defines how many times over budget the request rate may go before throttling engages, so a value of 1.0 or less would make the throttling probability math meaningless (or always-on). The check runs in the package-private constructor that all public constructors delegate to.","triggerScenarios":"Calling new AdaptiveThrottler(samplePeriodMs, sampleUpdateMs, overloadRatio) or the testing constructor with overloadRatio <= 1.0, e.g. 0.5 or 1.0.","commonSituations":"Misreading the parameter as a percentage (passing 0.5 meaning 50%); passing a default 0 sentinel; copying an example and tweaking the ratio down to test throttling behavior.","solutions":["Pass an overloadRatio strictly greater than 1.0 (e.g. 1.3 means throttling begins once traffic exceeds budget by 30%).","If you intended a percentage, convert: for 30% headroom pass 1.3, not 0.3.","Check config/constructor call sites for a 0 or 1.0 default and set a sane value like 1.2."],"exampleFix":"// before\nAdaptiveThrottler throttler = new AdaptiveThrottler(1000, 100, 1.0);\n// after\nAdaptiveThrottler throttler = new AdaptiveThrottler(1000, 100, 1.3);","handlingStrategy":"validation","validationCode":"if (overloadRatio <= 1.0) throw new IllegalArgumentException(\"overloadRatio must be > 1.0\");\nAdaptiveThrottler throttler = new AdaptiveThrottler(1000, 100, overloadRatio);","typeGuard":null,"tryCatchPattern":"try { new AdaptiveThrottler(1000, 100, ratio); } catch (IllegalArgumentException e) { ratio = 1.3; /* retry with default */ }","preventionTips":["Treat overloadRatio as a multiplier (>1.0), not a percentage.","Centralize throttler construction in one factory that clamps the ratio.","Unit-test constructor inputs at the boundaries (1.0 and 1.0001)."],"tags":["java","beam-io","constructor-validation","throttling"],"backgroundTag":"invalid-constructor-argument","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}