apache/beam · error · IllegalArgumentException

Provided timestamp %s must be within bounds [%s, %s].

Error message

Provided timestamp %s must be within bounds [%s, %s].

What it means

Apache Beam windows operate on Joda-Time Instants bounded by TIMESTAMP_MIN_VALUE and TIMESTAMP_MAX_VALUE, because window arithmetic (plus/minus window size) must not overflow. validateTimestampBounds throws IllegalArgumentException whenever a timestamp falls outside these bounds, keeping window computations within safe representable range.

Source

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

  /** Returns the inclusive upper bound of timestamps for values in this window. */
  public abstract Instant maxTimestamp();

  /** Parses a timestamp from the proto. */
  private static Instant extractTimestampFromProto(RunnerApi.BeamConstants.Constants constant) {
    return new Instant(
        Long.parseLong(
            constant.getValueDescriptor().getOptions().getExtension(RunnerApi.beamConstant)));
  }

  /**
   * Validates that a given timestamp is within min and max bounds.
   *
   * @param timestamp timestamp to validate
   */
  public static void validateTimestampBounds(Instant timestamp) {
    if (timestamp.isBefore(TIMESTAMP_MIN_VALUE) || timestamp.isAfter(TIMESTAMP_MAX_VALUE)) {
      throw new IllegalArgumentException(
          String.format(
              "Provided timestamp %s must be within bounds [%s, %s].",
              timestamp, TIMESTAMP_MIN_VALUE, TIMESTAMP_MAX_VALUE));
    }
  }
}

View on GitHub (pinned to 12126d8942)

Solutions

1. Clamp or sanitize the event timestamp before assigning it (e.g. cap at reasonable min/max, or use TimestampCombiner/skew limits).
2. Check the arithmetic that produced the Instant for unit errors (ms vs µs vs ns) and off-by-scale bugs.
3. Interpret out-of-bounds timestamps as malformed data and route the element to a dead-letter/output tag instead of windowing it.
4. If you need timestamps beyond the bounds, use a custom windowing/trigger design with a different time domain rather than exceeding Instant bounds.

Example fix

// before
windowed = ApplyWindows.<KV<String, Integer>>into(FixedWindows.of(SIZE))
    .apply(windowFn); // element has Instant far in future -> IllegalArgumentException
// after
Instant ts = element.getTimestamp();
if (ts.isBefore(BoundedWindow.TIMESTAMP_MIN_VALUE) || ts.isAfter(BoundedWindow.TIMESTAMP_MAX_VALUE)) {
  ts = ts.isBefore(BoundedWindow.TIMESTAMP_MIN_VALUE)
      ? BoundedWindow.TIMESTAMP_MIN_VALUE : BoundedWindow.TIMESTAMP_MAX_VALUE;
}
element = element.withTimestamp(ts);

public static boolean isWithinTimestampBounds(Instant ts) {
  return !ts.isBefore(BoundedWindow.TIMESTAMP_MIN_VALUE)
      && !ts.isAfter(BoundedWindow.TIMESTAMP_MAX_VALUE);
}
// call before assigning: checkArgument(isWithinTimestampBounds(ts), "bad timestamp: " + ts);

boolean safeTs(Instant ts) {
  return ts != null && isWithinTimestampBounds(ts);
}

try {
  BoundedWindow.validateTimestampBounds(ts);
} catch (IllegalArgumentException e) {
  LOG.warn("Timestamp {} out of bounds; clamping or dead-lettering", ts, e);
  // clamp to bounds or emit to dead-letter PCollection
}

When it happens

Trigger: Calling BoundedWindow.validateTimestampBounds (directly or via APIs that enforce bounds, e.g. window assignment or timestamp manipulation) with an Instant that is before TIMESTAMP_MIN_VALUE or after TIMESTAMP_MAX_VALUE — typically the result of adding a large Duration to a timestamp, or parsing a date far in the past/future.

Common situations: Deriving event timestamps from bad input data (year 0 or year 99999), repeatedly shifting timestamps by large durations in DoFns, converting epoch-millis strings with unit mistakes (nanos vs millis), and test fixtures using Instant.EPOCH plus huge offsets.

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.

Related errors

• Extract file timestamp failed: got file timestamp == 0.
• Distinct does not support merging windowing strategies, exce
• Inputs to Flatten had incompatible window windowFns: %s, %s
• Inputs to Flatten had incompatible triggers: %s, %s
• GroupByKey cannot be applied to non-bounded PCollection in t

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