apache/beam · error · IncompatibleWindowException

Only SlidingWindows objects with the same size, period and o

Error message

Only SlidingWindows objects with the same size, period and offset are compatible.

What it means

SlidingWindows.isCompatible returns true only when another WindowFn is also a SlidingWindows with equal period, size and offset. verifyCompatibility throws IncompatibleWindowException with this message when the check fails, preventing pipelines that would merge or combine incompatible sliding windowings.

Source

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

        return new IntervalWindow(new Instant(lastStart + period.getMillis()), size);
      }
    };
  }

  @Override
  public boolean isCompatible(WindowFn<?, ?> other) {
    return equals(other);
  }

  @Override
  public boolean assignsToOneWindow() {
    return !this.period.isShorterThan(this.size);
  }

  @Override
  public void verifyCompatibility(WindowFn<?, ?> other) throws IncompatibleWindowException {
    if (!this.isCompatible(other)) {
      throw new IncompatibleWindowException(
          other,
          String.format(
              "Only %s objects with the same size, period and offset are compatible.",
              SlidingWindows.class.getSimpleName()));
    }
  }

  @Override
  public void populateDisplayData(DisplayData.Builder builder) {
    super.populateDisplayData(builder);
    builder
        .add(DisplayData.item("size", size).withLabel("Window Size"))
        .add(DisplayData.item("period", period).withLabel("Window Period"))
        .add(DisplayData.item("offset", offset).withLabel("Window Start Offset"));
  }

  /** Return the last start of a sliding window that contains the timestamp. */
  private long lastStartFor(Instant timestamp) {

View on GitHub (pinned to 12126d8942)

Solutions

Use identical SlidingWindows.of(size).every(period[, offset]) on all PCollections being combined
Re-window one side with Window.into(theOtherWindowFn) before the join/flatten
Verify both pipeline branches read the same windowing config value

Example fix

// before
a.apply(Window.into(SlidingWindows.of(minutes(30)).every(minutes(5))))
b.apply(Window.into(SlidingWindows.of(minutes(60)).every(minutes(5))))
// after
b.apply(Window.into(SlidingWindows.of(minutes(30)).every(minutes(5))))

Defensive patterns

Strategy: validation

Validate before calling

if (!Objects.equals(cfgA.windowSpec(), cfgB.windowSpec())) throw new IllegalArgumentException("Branches must use identical SlidingWindows size/period/offset");

Type guard

boolean sameSlidingWindows(WindowFn<?,?> a, WindowFn<?,?> b) { return a instanceof SlidingWindows && b instanceof SlidingWindows && a.isCompatible(b); }

Try / catch

try { pipeline.apply(join); } catch (IncompatibleWindowException e) { b = b.apply(Window.into(slidingA)); }

Prevention

Drive windowing of all combined PCollections from one config object
Add pre-apply isCompatible checks in shared pipeline helpers
Re-window explicitly at join/flatten boundaries

When it happens

Trigger: Calling verifyCompatibility with a FixedWindows, Sessions, or a SlidingWindows with different size/period/offset — typically during pipeline graph validation of combined transforms.

Common situations: Joining streams windowed with different slide periods; a config change altering one side's window parameters but not the other; re-windowing one branch but forgetting the sibling branch.

Understand the failure class

Background: "is not a compatible type" / "cannot merge" errors: when a value's type doesn't match what the library requires — this error's family across 65 libraries.

Related errors

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