{"record":{"id":"ebbffeb9719b9852","repo":"apache/beam","slug":"watermark-column-time-unit-watermarkcolumntimeunit-is","errorCode":null,"errorMessage":"watermark_column_time_unit '{watermarkColumnTimeUnit}' is invalid. Please choose one of: {values}","messagePattern":"watermark_column_time_unit '(.+?)' is invalid\\. Please choose one of: (.+?)","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"sdks/java/io/iceberg/src/main/java/org/apache/beam/sdk/io/iceberg/IcebergScanConfig.java","lineNumber":551,"sourceCode":"    }\n\n    @Nullable String watermarkColumnTimeUnit = getWatermarkColumnTimeUnit();\n    if (watermarkColumnTimeUnit != null) {\n      checkArgument(\n          table\n                  .schema()\n                  .findField(\n                      checkStateNotNull(\n                          watermarkColumn,\n                          \"watermark_column_time_unit is configured without a specified watermark_column\"))\n                  .type()\n                  .typeId()\n              == LONG,\n          error(\"watermark_column_time_unit is only applicable for LONG columns.\"));\n      try {\n        TimeUnit.valueOf(watermarkColumnTimeUnit.toUpperCase(Locale.ENGLISH));\n      } catch (IllegalArgumentException e) {\n        throw new IllegalArgumentException(\n            error(\n                String.format(\n                    \"watermark_column_time_unit '%s' is invalid. Please choose one of: %s\",\n                    watermarkColumnTimeUnit, Arrays.toString(TimeUnit.values()))),\n            e);\n      }\n    }\n  }\n\n  private void validateMetadataColumns(Table table) {\n    List<String> metadataColumns = getMetadataColumns();\n    if (metadataColumns.isEmpty()) {\n      return;\n    }\n\n    Set<String> uniqueMetadataColumns = new LinkedHashSet<>(metadataColumns);\n    checkArgument(\n        uniqueMetadataColumns.size() == metadataColumns.size(),","sourceCodeStart":533,"sourceCodeEnd":569,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/io/iceberg/src/main/java/org/apache/beam/sdk/io/iceberg/IcebergScanConfig.java#L533-L569","documentation":"IcebergScanConfig.validate parses watermark_column_time_unit into java.util.concurrent.TimeUnit. If the configured string (uppercased) is not a TimeUnit constant, IllegalArgumentException is thrown with the valid choices. This validates the watermark column unit before building the scan.","triggerScenarios":"Setting watermark_column_time_unit to any string that is not one of TimeUnit.values() (NANOSECONDS, MICROSECONDS, MILLISECONDS, SECONDS, MINUTES, HOURS, DAYS) at IcebergScanConfig.java:551.","commonSituations":"Using lowercase-friendly units like 'micros' or 'seconds' that don't match enum names; units like 'MILLIS' which is not a Java TimeUnit; config generated from documentation for a different library.","solutions":["Set watermark_column_time_unit to an exact TimeUnit constant, e.g. MICROSECONDS or SECONDS.","Validate the unit string against TimeUnit values before submitting the pipeline.","Check that the unit matches the actual granularity of the watermark column's LONG values.","Normalize casing in config generation (TimeUnit.valueOf already uppercases, but the name must still match exactly)."],"exampleFix":"// before\nconfig.setWatermarkColumnTimeUnit(\"millis\");\n\n// after\nconfig.setWatermarkColumnTimeUnit(\"MILLISECONDS\");","handlingStrategy":"validation","validationCode":"boolean valid = unitStr == null\n    || Arrays.stream(TimeUnit.values())\n        .anyMatch(u -> u.name().equalsIgnoreCase(unitStr));\nif (!valid) throw new IllegalArgumentException(\"invalid watermark_column_time_unit: \" + unitStr);","typeGuard":null,"tryCatchPattern":"try {\n  scanConfig.validate();\n} catch (IllegalArgumentException e) {\n  LOG.error(\"Invalid watermark unit: {}\", e.getMessage());\n}","preventionTips":["Use exact TimeUnit constant names (e.g. MICROSECONDS, not 'micros').","Validate unit strings at config load time.","Match the unit to the watermark column's actual LONG granularity.","Generate config values from TimeUnit.values() rather than prose."],"tags":["java","iceberg","config-validation","enum","watermark"],"backgroundTag":"invalid-enum-value","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"}