What causes "consumerPollingTimeout should be > 0." in apache/beam?

Set consumerPollingTimeout to a positive value (seconds), e.g. 2.

apache/beam · error · IllegalArgumentException

consumerPollingTimeout should be > 0.

Error message

consumerPollingTimeout should be > 0.

What it means

The consumerPollingTimeout external config must be a positive number of seconds. setupExternalBuilder rejects non-positive values with an IllegalArgumentException because a zero/negative poll timeout would break the consumer polling loop.

Solutions

Set consumerPollingTimeout to a positive value (seconds), e.g. 2.
Omit the field entirely so the default of 2L is used.
Clamp the value in your config pipeline: timeout = Math.max(1, timeout).

Example fix

// before
{"consumerPollingTimeout": 0}
// after
{"consumerPollingTimeout": 2}

Defensive patterns

Strategy: validation

Validate before calling

if (t != null && t <= 0) throw new IllegalArgumentException("timeout>0 required");

Try / catch

try { build(cfg); } catch (IllegalArgumentException e) { clamp(); }

Prevention

Clamp timeouts >= 1; omit for default 2s

When it happens

Trigger: Setting config.consumerPollingTimeout to 0 or a negative value in the external KafkaIO configuration before building the pipeline.

Common situations: Copy-pasted template values of 0; interpreting the option as milliseconds and passing tiny/negative values; defaulting code that sets 0 meaning 'unset'.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

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

Appendix: source

Thrown at sdks/java/io/kafka/src/main/java/org/apache/beam/sdk/io/kafka/KafkaIO.java:928

        if (config.startReadTime != null) {
          builder.setStartReadTime(Instant.ofEpochMilli(config.startReadTime));
        }

        if (config.stopReadTime != null) {
          builder.setStopReadTime(Instant.ofEpochMilli(config.stopReadTime));
        }

        if (config.dynamicReadPollIntervalSeconds != null) {
          builder.setDynamicRead(true);
          builder.setWatchTopicPartitionDuration(
              Duration.standardSeconds(config.dynamicReadPollIntervalSeconds));
        } else {
          builder.setDynamicRead(false);
        }

        if (config.consumerPollingTimeout != null) {
          if (config.consumerPollingTimeout <= 0) {
            throw new IllegalArgumentException("consumerPollingTimeout should be > 0.");
          }
          builder.setConsumerPollingTimeout(config.consumerPollingTimeout);
        } else {
          builder.setConsumerPollingTimeout(2L);
        }

        if (config.redistribute != null) {
          builder.setRedistributed(config.redistribute);
          if (config.redistributeNumKeys != null) {
            builder.setRedistributeNumKeys((int) config.redistributeNumKeys);
          }
          if (config.allowDuplicates != null) {
            builder.setAllowDuplicates(config.allowDuplicates);
          }
          if (config.redistribute
              && (config.allowDuplicates == null || !config.allowDuplicates)
              && config.offsetDeduplication != null) {
            builder.setOffsetDeduplication(config.offsetDeduplication);

View on GitHub (pinned to 12126d8942)