{"record":{"id":"e4d1b25125f1e58e","repo":"apache/beam","slug":"provided-timestamp-s-must-be-within-bounds-s-s","errorCode":null,"errorMessage":"Provided timestamp %s must be within bounds [%s, %s].","messagePattern":"Provided timestamp (.+?) must be within bounds \\[(.+?), (.+?)\\]\\.","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"sdks/java/core/src/main/java/org/apache/beam/sdk/transforms/windowing/BoundedWindow.java","lineNumber":94,"sourceCode":"\n  /** Returns the inclusive upper bound of timestamps for values in this window. */\n  public abstract Instant maxTimestamp();\n\n  /** Parses a timestamp from the proto. */\n  private static Instant extractTimestampFromProto(RunnerApi.BeamConstants.Constants constant) {\n    return new Instant(\n        Long.parseLong(\n            constant.getValueDescriptor().getOptions().getExtension(RunnerApi.beamConstant)));\n  }\n\n  /**\n   * Validates that a given timestamp is within min and max bounds.\n   *\n   * @param timestamp timestamp to validate\n   */\n  public static void validateTimestampBounds(Instant timestamp) {\n    if (timestamp.isBefore(TIMESTAMP_MIN_VALUE) || timestamp.isAfter(TIMESTAMP_MAX_VALUE)) {\n      throw new IllegalArgumentException(\n          String.format(\n              \"Provided timestamp %s must be within bounds [%s, %s].\",\n              timestamp, TIMESTAMP_MIN_VALUE, TIMESTAMP_MAX_VALUE));\n    }\n  }\n}\n","sourceCodeStart":76,"sourceCodeEnd":101,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/core/src/main/java/org/apache/beam/sdk/transforms/windowing/BoundedWindow.java#L76-L101","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Clamp or sanitize the event timestamp before assigning it (e.g. cap at reasonable min/max, or use TimestampCombiner/skew limits).","Check the arithmetic that produced the Instant for unit errors (ms vs µs vs ns) and off-by-scale bugs.","Interpret out-of-bounds timestamps as malformed data and route the element to a dead-letter/output tag instead of windowing it.","If you need timestamps beyond the bounds, use a custom windowing/trigger design with a different time domain rather than exceeding Instant bounds."],"exampleFix":"// before\nwindowed = ApplyWindows.<KV<String, Integer>>into(FixedWindows.of(SIZE))\n    .apply(windowFn); // element has Instant far in future -> IllegalArgumentException\n// after\nInstant ts = element.getTimestamp();\nif (ts.isBefore(BoundedWindow.TIMESTAMP_MIN_VALUE) || ts.isAfter(BoundedWindow.TIMESTAMP_MAX_VALUE)) {\n  ts = ts.isBefore(BoundedWindow.TIMESTAMP_MIN_VALUE)\n      ? BoundedWindow.TIMESTAMP_MIN_VALUE : BoundedWindow.TIMESTAMP_MAX_VALUE;\n}\nelement = element.withTimestamp(ts);","handlingStrategy":"validation","validationCode":"public static boolean isWithinTimestampBounds(Instant ts) {\n  return !ts.isBefore(BoundedWindow.TIMESTAMP_MIN_VALUE)\n      && !ts.isAfter(BoundedWindow.TIMESTAMP_MAX_VALUE);\n}\n// call before assigning: checkArgument(isWithinTimestampBounds(ts), \"bad timestamp: \" + ts);","typeGuard":"boolean safeTs(Instant ts) {\n  return ts != null && isWithinTimestampBounds(ts);\n}","tryCatchPattern":"try {\n  BoundedWindow.validateTimestampBounds(ts);\n} catch (IllegalArgumentException e) {\n  LOG.warn(\"Timestamp {} out of bounds; clamping or dead-lettering\", ts, e);\n  // clamp to bounds or emit to dead-letter PCollection\n}","preventionTips":["Clamp event timestamps to plausible ranges at ingestion.","Watch for unit mistakes when converting epoch values to Instants.","Audit timestamp arithmetic (plus/minus) for possible overflow beyond bounds.","Route out-of-range timestamps to a dead-letter output instead of failing the pipeline."],"tags":["java","apache-beam","windowing","timestamp"],"backgroundTag":"value-out-of-range","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}