apache/beam · error · IllegalArgumentException

Except when using GlobalWindows, calling .triggering() to sp

Error message

Except when using GlobalWindows, calling .triggering() to specify a trigger requires that the allowed lateness be specified using .withAllowedLateness() to set the upper bound on how late data can arrive before being dropped. See Javadoc for more details.

What it means

In Apache Beam, a WindowingStrategy is only complete if a non-default trigger on a non-global window also declares an allowed lateness bound. Window.applicableTo() validates this at pipeline-construction time and throws IllegalArgumentException because, without a lateness bound, the runner cannot know when late data should be dropped relative to the custom trigger's windows of firing. GlobalWindows are exempt since all data is implicitly on time.

Source

Thrown at sdks/java/core/src/main/java/org/apache/beam/sdk/transforms/windowing/Window.java:360

    if (getOnTimeBehavior() != null) {
      result = result.withOnTimeBehavior(getOnTimeBehavior());
    }
    if (getTimestampCombiner() != null) {
      result = result.withTimestampCombiner(getTimestampCombiner());
    }
    return result;
  }

  private void applicableTo(PCollection<?> input) {
    WindowingStrategy<?, ?> outputStrategy =
        getOutputStrategyInternal(input.getWindowingStrategy());

    // Make sure that the windowing strategy is complete & valid.
    if (outputStrategy.isTriggerSpecified()
        && !(outputStrategy.getTrigger() instanceof DefaultTrigger)
        && !(outputStrategy.getWindowFn() instanceof GlobalWindows)
        && !outputStrategy.isAllowedLatenessSpecified()) {
      throw new IllegalArgumentException(
          "Except when using GlobalWindows,"
              + " calling .triggering() to specify a trigger requires that the allowed lateness"
              + " be specified using .withAllowedLateness() to set the upper bound on how late"
              + " data can arrive before being dropped. See Javadoc for more details.");
    }

    if (!outputStrategy.isModeSpecified() && canProduceMultiplePanes(outputStrategy)) {
      throw new IllegalArgumentException(
          "Calling .triggering() to specify a trigger or calling .withAllowedLateness() to"
              + " specify an allowed lateness greater than zero requires that the accumulation"
              + " mode be specified using .discardingFiredPanes() or .accumulatingFiredPanes()."
              + " See Javadoc for more details.");
    }
  }

  private boolean canProduceMultiplePanes(WindowingStrategy<?, ?> strategy) {
    // The default trigger is Repeatedly.forever(AfterWatermark.pastEndOfWindow()); This fires
    // for every late-arriving element if allowed lateness is nonzero, and thus we must have

View on GitHub (pinned to 12126d8942)

Solutions

1. Add .withAllowedLateness(Duration) (e.g. .withAllowedLateness(StandardMinutes.of(1))) after .triggering(...) on the Window transform.
2. If you truly need no lateness semantics, check whether GlobalWindows is the right WindowFn, which exempts you from this requirement.
3. If a custom trigger is unnecessary, remove .triggering(...) and use the DefaultTrigger, which requires no lateness.

Example fix

// before
PCollection<T> out = items.apply(Window.<T>into(FixedWindows.of(StandardMinutes.of(1)))
    .triggering(AfterWatermark.pastEndOfWindow()));
// after
PCollection<T> out = items.apply(Window.<T>into(FixedWindows.of(StandardMinutes.of(1)))
    .triggering(AfterWatermark.pastEndOfWindow())
    .withAllowedLateness(StandardMinutes.of(1)));

if (windowFn instanceof GlobalWindows == false && trigger != null && !(trigger instanceof DefaultTrigger) && allowedLateness == null) {
  throw new IllegalArgumentException("custom trigger requires withAllowedLateness(...)");
}

When it happens

Trigger: Calling Window.into(fn).triggering(AfterWatermark.pastEndOfWindow()) (or any trigger other than DefaultTrigger) with a non-GlobalWindows WindowFn and never calling .withAllowedLateness(...).

Common situations: Building time-based windowing pipelines with custom triggers (e.g. early firings via AfterWatermark or Repeatedly.forever) and forgetting the lateness setting; copying trigger code from examples that used GlobalWindows; refactors where .withAllowedLateness was dropped.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• Calling .triggering() to specify a trigger or calling .withA
• Inputs to Flatten had incompatible triggers: %s, %s
• Only %s objects with the same window supplier are compatible
• ApproximateUnique.PerKey needs an estimation error between 1
• ApproximateUnique.PerKey requires its input to use KvCoder

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