apache/beam · error · IncompatibleWindowException

Only objects with the same number of years, month of year…

Error message

Only %s objects with the same number of years, month of year, day of month, start date and time zone are compatible.

What it means

CalendarWindows.YearsWindows.verifyCompatibility throws IncompatibleWindowException when grouping streams whose YearsWindows differ in number of years, month of year, day of month, startDate, or time zone. Identical window functions are required for element-wise window alignment in joins and merges.

Solutions

Use the exact same YearsWindows instance/values on both sides of the merge.
Define the yearly window once in shared configuration.
Re-window one input into the other's windows before joining.
Drop to GlobalWindows when calendar alignment is not needed for the merge.

Example fix

// before
PCollection<A> a = inA.apply(Window.into(CalendarWindows.years(1, Month.JANUARY, 1, START, ZONE)));
PCollection<B> b = inB.apply(Window.into(CalendarWindows.years(1, Month.JULY, 1, START, ZONE)));
// after
CalendarWindows.YearsWindows win = CalendarWindows.years(1, Month.JANUARY, 1, START, ZONE);
PCollection<A> a = inA.apply(Window.into(win));
PCollection<B> b = inB.apply(Window.into(win));

Defensive patterns

Strategy: validation

Validate before calling

YearsWindows a = CalendarWindows.years(n, month, day, START, ZONE);
YearsWindows b = (YearsWindows) other;
boolean compatible = a.getYears() == b.getYears()
    && a.getMonth() == b.getMonth()
    && a.getDayOfMonth() == b.getDayOfMonth()
    && a.getStartDate().equals(b.getStartDate())
    && a.getTimeZone().equals(b.getTimeZone());

Try / catch

try {
  windowFn1.verifyCompatibility(windowFn2);
} catch (IncompatibleWindowException e) {
  throw new IllegalStateException("YearsWindows differ (years/month/day/startDate/zone)", e);
}

Prevention

Use one shared YearsWindows instance for all yearly streams.
Document fiscal-year anchors (month/day) in shared config.
Fail fast in setup by calling verifyCompatibility across inputs.
Convert to GlobalWindows before merging when calendar alignment is not required.

When it happens

Trigger: Merging/CoGroupByKey of PCollections windowed with CalendarWindows.years(n, ...) having different years(), months, days, startDate, or timeZone values.

Common situations: Yearly batch streams configured with different anchors (e.g. starting Jan 1 vs fiscal-year July 1) combined in a single pipeline.

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

Appendix: source

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

    }

    @Override
    public boolean isCompatible(WindowFn<?, ?> other) {
      if (!(other instanceof YearsWindows)) {
        return false;
      }
      YearsWindows that = (YearsWindows) other;
      return number == that.number
          && monthOfYear == that.monthOfYear
          && dayOfMonth == that.dayOfMonth
          && Objects.equals(startDate, that.startDate)
          && Objects.equals(timeZone, that.timeZone);
    }

    @Override
    public void verifyCompatibility(WindowFn<?, ?> other) throws IncompatibleWindowException {
      if (!this.isCompatible(other)) {
        throw new IncompatibleWindowException(
            other,
            String.format(
                "Only %s objects with the same number of years, month of year, "
                    + "day of month, start date and time zone are compatible.",
                YearsWindows.class.getSimpleName()));
      }
    }

    @Override
    public void populateDisplayData(DisplayData.Builder builder) {
      super.populateDisplayData(builder);

      builder
          .add(DisplayData.item("numYears", number).withLabel("Window Years"))
          .addIfNotDefault(
              DisplayData.item("startDate", new DateTime(startDate, timeZone).toInstant())
                  .withLabel("Window Start Date"),
              new DateTime(DEFAULT_START_DATE, DateTimeZone.UTC).toInstant());

View on GitHub (pinned to 12126d8942)