{"record":{"id":"70ae533258da5464","repo":"apache/beam","slug":"datetimeexception-message","errorCode":null,"errorMessage":"<DateTimeException message>","messagePattern":"<DateTimeException message>","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"sdks/java/io/google-cloud-platform/src/main/java/org/apache/beam/sdk/io/gcp/bigquery/CivilTimeEncoder.java","lineNumber":172,"sourceCode":"   * <pre>\n   *      3         2         1\n   * MSB 10987654321098765432109876543210 LSB\n   *                    | H ||  M ||  S |\n   * </pre>\n   *\n   * @see #encodePacked32TimeSeconds(java.time.LocalTime)\n   */\n  @SuppressWarnings(\"GoodTime-ApiWithNumericTimeUnit\")\n  public static java.time.LocalTime decodePacked32TimeSecondsAsJavaTime(int bitFieldTimeSeconds) {\n    checkValidBitField(bitFieldTimeSeconds, TIME_SECONDS_MASK);\n    int hourOfDay = getFieldFromBitField(bitFieldTimeSeconds, HOUR_MASK, HOUR_SHIFT);\n    int minuteOfHour = getFieldFromBitField(bitFieldTimeSeconds, MINUTE_MASK, MINUTE_SHIFT);\n    int secondOfMinute = getFieldFromBitField(bitFieldTimeSeconds, SECOND_MASK, SECOND_SHIFT);\n    // java.time.LocalTime validates the input parameters.\n    try {\n      return java.time.LocalTime.of(hourOfDay, minuteOfHour, secondOfMinute);\n    } catch (java.time.DateTimeException e) {\n      throw new IllegalArgumentException(e.getMessage(), e);\n    }\n  }\n\n  /**\n   * Encodes {@code time} as a 8-byte integer with microseconds precision.\n   *\n   * <p>Encoding is as the following:\n   *\n   * <pre>\n   *        6         5         4         3         2         1\n   * MSB 3210987654321098765432109876543210987654321098765432109876543210 LSB\n   *                                | H ||  M ||  S ||-------micros-----|\n   * </pre>\n   *\n   * @see #decodePacked64TimeMicros(long)\n   * @see #encodePacked64TimeMicros(java.time.LocalTime)\n   */\n  @SuppressWarnings(\"GoodTime\") // should accept a java.time.LocalTime","sourceCodeStart":154,"sourceCodeEnd":190,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/io/google-cloud-platform/src/main/java/org/apache/beam/sdk/io/gcp/bigquery/CivilTimeEncoder.java#L154-L190","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Verify the integer was produced by the matching CivilTimeEncoder.encodeTime*Seconds method (same precision)","Validate the packed value's hour/minute/second ranges before decoding","Re-encode the data with CivilTimeEncoder if it came from another system","Catch IllegalArgumentException and log the raw packed value for diagnosis"],"exampleFix":"// before: decoding micros-encoded value with seconds decoder\nlong packed = CivilTimeEncoder.encodeTimeMicros(LocalTime.of(12, 30, 45));\nLocalTime t = CivilTimeEncoder.decodePacked32TimeSecondsAsJavaTime((int) packed);\n// after\nlong packed = CivilTimeEncoder.encodeTimeSeconds(LocalTime.of(12, 30, 45));\nLocalTime t = CivilTimeEncoder.decodePacked32TimeSecondsAsJavaTime((int) packed);","handlingStrategy":"validation","validationCode":"if (hourOfDay < 0 || hourOfDay > 23 || minuteOfHour < 0 || minuteOfHour > 59 || secondOfMinute < 0 || secondOfMinute > 59) {\n  throw new IllegalArgumentException(\"Invalid packed time components: \" + hourOfDay + \":\" + minuteOfHour + \":\" + secondOfMinute);\n}","typeGuard":"boolean isValidPackedTime(int hour, int minute, int second) { return hour >= 0 && hour < 24 && minute >= 0 && minute < 60 && second >= 0 && second < 60; }","tryCatchPattern":"try { t = CivilTimeEncoder.decodePacked32TimeSecondsAsJavaTime(packed); } catch (IllegalArgumentException e) { LOG.error(\"Bad packed time %d: %s\", packed, e.getMessage()); t = null; }","preventionTips":["Always pair encode/decode with matching precision (seconds vs micros)","Round-trip test: decode(encode(t)) equals t","Reject negative or suspiciously large packed integers before decoding"],"tags":["bigquery","time-encoding","value-out-of-range"],"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-20T03:17:13.778Z"}