apache/beam · error · IllegalArgumentException

<DateTimeException message>

Error message

<DateTimeException message>

What it means

CivilTimeEncoder.decodePacked32TimeSecondsAsJavaTime unpacks a packed 32-bit time bit-field into hour/minute/second and builds a java.time.LocalTime. LocalTime validates the fields; if any component is out of range (e.g. hour 24+), the DateTimeException is rethrown as an IllegalArgumentException with the underlying message.

Solutions

1. Verify the integer was produced by the matching CivilTimeEncoder.encodeTime*Seconds method (same precision)
2. Validate the packed value's hour/minute/second ranges before decoding
3. Re-encode the data with CivilTimeEncoder if it came from another system
4. Catch IllegalArgumentException and log the raw packed value for diagnosis

Example fix

// before: decoding micros-encoded value with seconds decoder
long packed = CivilTimeEncoder.encodeTimeMicros(LocalTime.of(12, 30, 45));
LocalTime t = CivilTimeEncoder.decodePacked32TimeSecondsAsJavaTime((int) packed);
// after
long packed = CivilTimeEncoder.encodeTimeSeconds(LocalTime.of(12, 30, 45));
LocalTime t = CivilTimeEncoder.decodePacked32TimeSecondsAsJavaTime((int) packed);

if (hourOfDay < 0 || hourOfDay > 23 || minuteOfHour < 0 || minuteOfHour > 59 || secondOfMinute < 0 || secondOfMinute > 59) {
  throw new IllegalArgumentException("Invalid packed time components: " + hourOfDay + ":" + minuteOfHour + ":" + secondOfMinute);
}

boolean isValidPackedTime(int hour, int minute, int second) { return hour >= 0 && hour < 24 && minute >= 0 && minute < 60 && second >= 0 && second < 60; }

try { t = CivilTimeEncoder.decodePacked32TimeSecondsAsJavaTime(packed); } catch (IllegalArgumentException e) { LOG.error("Bad packed time %d: %s", packed, e.getMessage()); t = null; }

When it happens

Trigger: Decoding a packed BigQuery-stored TIME integer whose bit fields encode invalid values — corrupted data, decoding with the wrong precision encoder/decoder pair, or values written by a different encoding scheme (seconds vs microseconds).

Common situations: Mixing CivilTimeEncoder.encodeTimeSeconds with decodePacked*TimeMicros (or vice versa); reading integers not produced by CivilTimeEncoder; byte-order or shift corruption from storage/serialization; negative or truncated integers.

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

• max_insert_payload_size can only go up to 10485760 bytes…
• A BigQuery table or a query must be specified
• A function must be provided to convert the input type into…
• A schema is required in order to prepare rows for writing…
• A schema must be provided when writing to BigQuery using…

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

Appendix: source

Thrown at sdks/java/io/google-cloud-platform/src/main/java/org/apache/beam/sdk/io/gcp/bigquery/CivilTimeEncoder.java:172

   * <pre>
   *      3         2         1
   * MSB 10987654321098765432109876543210 LSB
   *                    | H ||  M ||  S |
   * </pre>
   *
   * @see #encodePacked32TimeSeconds(java.time.LocalTime)
   */
  @SuppressWarnings("GoodTime-ApiWithNumericTimeUnit")
  public static java.time.LocalTime decodePacked32TimeSecondsAsJavaTime(int bitFieldTimeSeconds) {
    checkValidBitField(bitFieldTimeSeconds, TIME_SECONDS_MASK);
    int hourOfDay = getFieldFromBitField(bitFieldTimeSeconds, HOUR_MASK, HOUR_SHIFT);
    int minuteOfHour = getFieldFromBitField(bitFieldTimeSeconds, MINUTE_MASK, MINUTE_SHIFT);
    int secondOfMinute = getFieldFromBitField(bitFieldTimeSeconds, SECOND_MASK, SECOND_SHIFT);
    // java.time.LocalTime validates the input parameters.
    try {
      return java.time.LocalTime.of(hourOfDay, minuteOfHour, secondOfMinute);
    } catch (java.time.DateTimeException e) {
      throw new IllegalArgumentException(e.getMessage(), e);
    }
  }

  /**
   * Encodes {@code time} as a 8-byte integer with microseconds precision.
   *
   * <p>Encoding is as the following:
   *
   * <pre>
   *        6         5         4         3         2         1
   * MSB 3210987654321098765432109876543210987654321098765432109876543210 LSB
   *                                | H ||  M ||  S ||-------micros-----|
   * </pre>
   *
   * @see #decodePacked64TimeMicros(long)
   * @see #encodePacked64TimeMicros(java.time.LocalTime)
   */
  @SuppressWarnings("GoodTime") // should accept a java.time.LocalTime

View on GitHub (pinned to 12126d8942)