{"record":{"id":"a69cb41fc6b169cf","repo":"apache/beam","slug":"fixedwindows-windowingstrategies-must-have-0-offset-size","errorCode":null,"errorMessage":"FixedWindows WindowingStrategies must have 0 <= offset < size","messagePattern":"FixedWindows WindowingStrategies must have 0 <= offset < size","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"sdks/java/core/src/main/java/org/apache/beam/sdk/transforms/windowing/FixedWindows.java","lineNumber":66,"sourceCode":"   * where 0 is the epoch.\n   */\n  public static FixedWindows of(Duration size) {\n    return new FixedWindows(size, Duration.ZERO);\n  }\n\n  /**\n   * Partitions the timestamp space into half-open intervals of the form [N * size + offset, (N + 1)\n   * * size + offset), where 0 is the epoch.\n   *\n   * @throws IllegalArgumentException if offset is not in [0, size)\n   */\n  public FixedWindows withOffset(Duration offset) {\n    return new FixedWindows(size, offset);\n  }\n\n  private FixedWindows(Duration size, Duration offset) {\n    if (offset.isShorterThan(Duration.ZERO) || !offset.isShorterThan(size)) {\n      throw new IllegalArgumentException(\n          \"FixedWindows WindowingStrategies must have 0 <= offset < size\");\n    }\n    this.size = size;\n    this.offset = offset;\n  }\n\n  @Override\n  public IntervalWindow assignWindow(Instant timestamp) {\n    Instant start =\n        new Instant(\n            timestamp.getMillis()\n                - timestamp.plus(size).minus(offset).getMillis() % size.getMillis());\n\n    // The global window is inclusive of max timestamp, while interval window excludes its\n    // upper bound\n    Instant endOfGlobalWindow = GlobalWindow.INSTANCE.maxTimestamp().plus(Duration.millis(1));\n\n    // The end of the window is either start + size if that is within the allowable range, otherwise","sourceCodeStart":48,"sourceCodeEnd":84,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/core/src/main/java/org/apache/beam/sdk/transforms/windowing/FixedWindows.java#L48-L84","documentation":"FixedWindows.of(...).withOffset(Duration) constructs a FixedWindows whose offset must satisfy 0 <= offset < size. The private constructor validates this and throws IllegalArgumentException otherwise, because an offset >= size is equivalent to a different window size and would corrupt window alignment.","triggerScenarios":"Calling FixedWindows.of(Duration.ofMinutes(5)).withOffset(Duration.ofMinutes(10)) or withOffset(Duration.ofMinutes(-1)) — negative offset, or offset equal to or larger than the window size.","commonSituations":"Building windows from user-supplied config where offset and size come from separate settings without a cross-check; passing offset in the wrong unit (seconds vs minutes) so it silently exceeds the size.","solutions":["Ensure offset >= Duration.ZERO and strictly less than the window size before calling withOffset.","If the desired offset exceeds size, shrink it modulo the size (offset % size) or redefine the window size.","Validate user-provided size/offset config at startup with a clear error message.","Use Durations.ofX helpers consistently to avoid unit mistakes between size and offset."],"exampleFix":"// before\nDuration size = Durations.minutes(5);\nDuration offset = Durations.minutes(10); // offset >= size -> IllegalArgumentException\nFixedWindows win = FixedWindows.of(size).withOffset(offset);\n// after\nDuration offset = Durations.minutes(3);\ncheckArgument(offset.isShorterThan(size) && !offset.isShorterThan(Duration.ZERO), \"0 <= offset < size\");\nFixedWindows win = FixedWindows.of(size).withOffset(offset);","handlingStrategy":"validation","validationCode":"public static FixedWindows safeFixedWindows(Duration size, Duration offset) {\n  checkArgument(!offset.isShorterThan(Duration.ZERO), \"offset must be >= 0\");\n  checkArgument(offset.isShorterThan(size), \"offset must be < size (got %s >= %s)\", offset, size);\n  return FixedWindows.of(size).withOffset(offset);\n}","typeGuard":null,"tryCatchPattern":"try {\n  return FixedWindows.of(size).withOffset(offset);\n} catch (IllegalArgumentException e) {\n  LOG.warn(\"Invalid fixed-window offset {} for size {}; using offset %% size\", offset, size);\n  return FixedWindows.of(size).withOffset(offset.minus(size.dividedBy(\n      size.getMillis() <= 0 ? 1 : size.getMillis() / Math.max(1, size.getMillis() / Math.max(1, offset.getMillis() / size.getMillis() == 0 ? 1 : 0)))));\n}","preventionTips":["Validate size/offset coming from user config before building windows.","Keep offset and size in the same Duration units (use Durations helpers).","Reduce any desired offset modulo the window size.","Add a startup config check: 0 <= offset < size."],"tags":["java","apache-beam","windowing","configuration"],"backgroundTag":"invalid-config-value","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-20T03:17:13.778Z"}