{"record":{"id":"82521e016c399809","repo":"apache/beam","slug":"throttledelaysecs-must-be-greater-than-0","errorCode":null,"errorMessage":"throttleDelaySecs must be greater than 0","messagePattern":"throttleDelaySecs must be greater than 0","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"sdks/java/io/components/src/main/java/org/apache/beam/sdk/io/components/throttling/ReactiveThrottler.java","lineNumber":59,"sourceCode":"  /**\n   * Initializes the ReactiveThrottler.\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   * @param namespace the namespace to use for logging and signaling throttling is occurring.\n   * @param throttleDelaySecs the amount of time in seconds to wait after preemptively throttled\n   *     requests.\n   */\n  public ReactiveThrottler(\n      long samplePeriodMs,\n      long sampleUpdateMs,\n      double overloadRatio,\n      String namespace,\n      int throttleDelaySecs) {\n    super(samplePeriodMs, sampleUpdateMs, overloadRatio);\n    if (throttleDelaySecs <= 0) {\n      throw new IllegalArgumentException(\"throttleDelaySecs must be greater than 0\");\n    }\n    this.throttlingSignaler = new ThrottlingSignaler(namespace);\n    this.throttleDelaySecs = throttleDelaySecs;\n  }\n\n  /**\n   * Stops request code from advancing while the underlying AdaptiveThrottler is signaling to\n   * preemptively throttle the request. Automatically handles logging the throttling and signaling\n   * to the SDK harness that the request is being throttled. This should be called in any context\n   * where a call to a remote service is being contacted prior to the call being performed.\n   */\n  public void throttle() throws InterruptedException {\n    if (throttleRequest(System.currentTimeMillis())) {\n      LOG.debug(\"Delaying request for {} seconds due to previous failures\", throttleDelaySecs);\n      Thread.sleep(throttleDelaySecs * SECONDS_TO_MILLISECONDS);\n      throttlingSignaler.signalThrottling(throttleDelaySecs * SECONDS_TO_MILLISECONDS);\n    }\n  }","sourceCodeStart":41,"sourceCodeEnd":77,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/io/components/src/main/java/org/apache/beam/sdk/io/components/throttling/ReactiveThrottler.java#L41-L77","documentation":"ReactiveThrottler extends AdaptiveThrottler and adds a shared throttling signal with a fixed delay; its constructor rejects throttleDelaySecs <= 0 with an IllegalArgumentException. The delay is how long clients back off after an overloaded signal is observed, so a zero or negative delay is nonsensical. The check runs after the superclass overloadRatio validation.","triggerScenarios":"Calling new ReactiveThrottler(samplePeriodMs, sampleUpdateMs, overloadRatio, namespace, throttleDelaySecs) with throttleDelaySecs <= 0, e.g. 0 or -1.","commonSituations":"Passing 0 hoping for 'no delay'; loading the value from config where it defaults to 0; accidentally swapping argument order so throttleDelaySecs receives a negative/zero value.","solutions":["Pass a positive throttleDelaySecs (e.g. 30 for a 30-second back off).","Clamp or default the config value before constructing: throttleDelaySecs <= 0 ? 30 : throttleDelaySecs.","Verify constructor argument order so the delay parameter isn't receiving another value."],"exampleFix":"// before\nReactiveThrottler t = new ReactiveThrottler(1000, 100, 1.3, \"myApi\", 0);\n// after\nReactiveThrottler t = new ReactiveThrottler(1000, 100, 1.3, \"myApi\", 30);","handlingStrategy":"validation","validationCode":"if (throttleDelaySecs <= 0) throw new IllegalArgumentException(\"throttleDelaySecs must be > 0\");\nReactiveThrottler t = new ReactiveThrottler(1000, 100, 1.3, namespace, throttleDelaySecs);","typeGuard":null,"tryCatchPattern":"try { new ReactiveThrottler(sp, su, or, ns, delay); } catch (IllegalArgumentException e) { delay = 30; /* fall back to sane delay */ }","preventionTips":["Clamp config-sourced delays to a positive default (e.g. 30s).","Document parameter order; build via a builder or named config object to avoid transposition.","Assert configuration sanity in a startup check before pipeline launch."],"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"}