apache/beam · error · IllegalArgumentException

overloadRatio must be greater than 1.0

Error message

overloadRatio must be greater than 1.0

What it means

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.

Source

Thrown at sdks/java/io/components/src/main/java/org/apache/beam/sdk/io/components/throttling/AdaptiveThrottler.java:60

  private final MovingFunction successfulRequests;
  private final double overloadRatio;
  private final Random random;

  /**
   * Initializes AdaptiveThrottler.
   *
   * @param samplePeriodMs length of history to consider, in ms, to set throttling.
   * @param sampleUpdateMs granularity of time buckets that we store data in, in ms.
   * @param overloadRatio the target ratio between requests sent and successful requests.
   */
  public AdaptiveThrottler(long samplePeriodMs, long sampleUpdateMs, double overloadRatio) {
    this(samplePeriodMs, sampleUpdateMs, overloadRatio, new Random());
  }

  // visible for testing
  AdaptiveThrottler(long samplePeriodMs, long sampleUpdateMs, double overloadRatio, Random random) {
    if (overloadRatio <= 1.0) {
      throw new IllegalArgumentException("overloadRatio must be greater than 1.0");
    }
    this.allRequests = new MovingFunction(samplePeriodMs, sampleUpdateMs, 1, 1, Sum.ofLongs());
    this.successfulRequests =
        new MovingFunction(samplePeriodMs, sampleUpdateMs, 1, 1, Sum.ofLongs());
    this.overloadRatio = overloadRatio;
    this.random = random;
  }

  protected double throttlingProbability(long nowMsSinceEpoch) {
    long allReqs = allRequests.get(nowMsSinceEpoch);
    if (!allRequests.isSignificant()) {
      return 0.0;
    }
    long successfulReqs = successfulRequests.get(nowMsSinceEpoch);
    double prob = (allReqs - overloadRatio * successfulReqs) / (allReqs + MIN_REQUESTS);
    return Math.max(0.0, prob);
  }

View on GitHub (pinned to 12126d8942)

Solutions

1. Pass an overloadRatio strictly greater than 1.0 (e.g. 1.3 means throttling begins once traffic exceeds budget by 30%).
2. If you intended a percentage, convert: for 30% headroom pass 1.3, not 0.3.
3. Check config/constructor call sites for a 0 or 1.0 default and set a sane value like 1.2.

Example fix

// before
AdaptiveThrottler throttler = new AdaptiveThrottler(1000, 100, 1.0);
// after
AdaptiveThrottler throttler = new AdaptiveThrottler(1000, 100, 1.3);

if (overloadRatio <= 1.0) throw new IllegalArgumentException("overloadRatio must be > 1.0");
AdaptiveThrottler throttler = new AdaptiveThrottler(1000, 100, overloadRatio);

try { new AdaptiveThrottler(1000, 100, ratio); } catch (IllegalArgumentException e) { ratio = 1.3; /* retry with default */ }

When it happens

Trigger: Calling new AdaptiveThrottler(samplePeriodMs, sampleUpdateMs, overloadRatio) or the testing constructor with overloadRatio <= 1.0, e.g. 0.5 or 1.0.

Common situations: 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.

Related errors

• throttleDelaySecs must be greater than 0
• requires an input Schema. Note that only Row or user classe
• header does not contain required %s field: %s
• Unsupported type: , consider using withCustomRecordParsing
• field was received -- type mismatch

AI-assisted analysis of apache/beam@12126d8942 (2026-09-13). Data as JSON: /api/errors/754d52565e277b20. Report an issue: GitHub.