apache/beam · error · IncompatibleWindowException

Only FixedWindows objects with the same size and offset are…

Error message

Only FixedWindows objects with the same size and offset are compatible.

What it means

FixedWindows.verifyCompatibility throws IncompatibleWindowException when a FixedWindows-windowed PCollection is merged with one using FixedWindows of a different size or offset. Beam can only align windows element-wise across sources when both sides use identical window size and offset.

Solutions

Use the same FixedWindows size and offset on every input to the merge.
Define the FixedWindows factory (size, offset) in shared constants/config consumed by both pipelines.
Re-window one PCollection into the other's FixedWindows before the join.
If alignment is unnecessary, merge using GlobalWindows (Window.into(GlobalWindows())) first.

Example fix

// before
PCollection<A> a = inA.apply(Window.into(FixedWindows.of(Duration.standardMinutes(5))));
PCollection<B> b = inB.apply(Window.into(FixedWindows.of(Duration.standardMinutes(10))));
// after
FixedWindows win = FixedWindows.of(Duration.standardMinutes(5)).withOffset(OFFSET);
PCollection<A> a = inA.apply(Window.into(win));
PCollection<B> b = inB.apply(Window.into(win));

Defensive patterns

Strategy: validation

Validate before calling

FixedWindows a = FixedWindows.of(Duration.standardMinutes(5)).withOffset(OFFSET);
if (other instanceof FixedWindows) {
  FixedWindows b = (FixedWindows) other;
  boolean compatible = a.getSize().equals(b.getSize()) && a.getOffset().equals(b.getOffset());
}

Try / catch

try {
  fixedWindows.verifyCompatibility(otherWindowFn);
} catch (IncompatibleWindowException e) {
  throw new IllegalStateException("FixedWindows size/offset mismatch across merge inputs", e);
}

Prevention

Build all FixedWindows from one shared constant/factory.
Record window size and offset alongside each pipeline's config.
Check window equality in integration tests before joins.
Use window().calling flow: re-window one side to match before CoGroupByKey.

When it happens

Trigger: CoGroupByKey/Join/Flatten of PCollections where one used FixedWindows.of(Duration.ofMinutes(5)) and the other FixedWindows.of(Duration.ofMinutes(10)) or a different withOffset value.

Common situations: Two jobs written with different tumbling-window sizes joined downstream; a refactor changed one side's size/offset; offset added to only one side for timezone alignment.

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/6cb9ab8da14c26cb. Report an issue: GitHub.

Appendix: source

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

        .add(DisplayData.item("size", size).withLabel("Window Duration"))
        .addIfNotDefault(
            DisplayData.item("offset", offset).withLabel("Window Start Offset"), Duration.ZERO);
  }

  @Override
  public Coder<IntervalWindow> windowCoder() {
    return IntervalWindow.getCoder();
  }

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

  @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 and offset are compatible.",
              FixedWindows.class.getSimpleName()));
    }
  }

  public Duration getSize() {
    return size;
  }

  public Duration getOffset() {
    return offset;
  }

  @Override
  public boolean equals(@Nullable Object object) {
    if (!(object instanceof FixedWindows)) {

View on GitHub (pinned to 12126d8942)