apache/beam · error · IllegalArgumentException

Unknown timestamp truncation option: %s

Error message

Unknown timestamp truncation option: %s

What it means

Thrown by BigQueryUtils.convertAvroFormat when converting a DATETIME-typed Avro value from BigQuery and the ConversionOptions' TruncateTimestamps value is neither TRUNCATE nor REJECT. This is an internal default-branch guard: the enum should only ever have those two values, so hitting it means an unknown/invalid enum value reached the converter. It is an IllegalArgumentException, not a data error.

Source

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

      case BYTE:
      case INT16:
      case INT32:
      case INT64:
      case FLOAT:
      case DOUBLE:
      case STRING:
      case BYTES:
      case BOOLEAN:
        return convertAvroPrimitiveTypes(beamFieldTypeName, avroValue);
      case DATETIME:
        // Expecting value in microseconds.
        switch (options.getTruncateTimestamps()) {
          case TRUNCATE:
            return truncateToMillis(avroValue);
          case REJECT:
            return safeToMillis(avroValue);
          default:
            throw new IllegalArgumentException(
                String.format(
                    "Unknown timestamp truncation option: %s", options.getTruncateTimestamps()));
        }
      case DECIMAL:
        return convertAvroNumeric(avroValue);
      case ARRAY:
        return convertAvroArray(beamFieldType, avroValue, options);
      case LOGICAL_TYPE:
        LogicalType<?, ?> logicalType =
            Preconditions.checkArgumentNotNull(beamFieldType.getLogicalType());
        String identifier = logicalType.getIdentifier();
        if (SqlTypes.DATE.getIdentifier().equals(identifier)) {
          return convertAvroDate(avroValue);
        } else if (SqlTypes.TIME.getIdentifier().equals(identifier)) {
          return convertAvroTime(avroValue);
        } else if (SqlTypes.DATETIME.getIdentifier().equals(identifier)) {
          return convertAvroDateTime(avroValue);
        } else if (SQL_DATE_TIME_TYPES.contains(identifier)) {

View on GitHub (pinned to 12126d8942)

Solutions

  1. Use only the two supported values: BigQueryIO.withTruncatedTimestamps() (TRUNCATE) or the default REJECT mode; do not construct ConversionOptions manually.
  2. Ensure all pipeline stages and runners use the same Beam SDK version as the code compiling this switch.
  3. Rebuild against a single Beam version so enum and consumer are in sync.
  4. If you maintain a fork, replace the default branch with a hard failure listing valid options or route unknown values to REJECT.

Example fix

// before
ConversionOptions opts = new ConversionOptions(someEnumFromConfig);
// after
ConversionOptions opts = useTruncation
    ? ConversionOptions.truncateTimestamps()
    : ConversionOptions.rejectTimestamps(); // only supported enum values
Defensive patterns

Strategy: validation

Validate before calling

// Java: validate the option before conversion
if (opts.getTruncateTimestamps() != ConversionOptions.TruncateTimestamps.TRUNCATE
    && opts.getTruncateTimestamps() != ConversionOptions.TruncateTimestamps.REJECT) {
  throw new IllegalArgumentException("truncateTimestamps must be TRUNCATE or REJECT");
}

Try / catch

try { return BigQueryIO.readTableRows().from(table).apply(...); } catch (IllegalArgumentException e) { if (e.getMessage().startsWith("Unknown timestamp truncation option")) { /* rebuild options with TRUNCATE/REJECT and retry */ } throw e; }

Prevention

When it happens

Trigger: BigQueryIO.readTableRows / avro conversion path is invoked with a ConversionOptions whose getTruncateTimestamps() returns a value outside {TRUNCATE, REJECT} — e.g. a custom or deserialized ConversionOptions, or a future enum constant used with an older Beam version. Also hit at BigQueryUtils.java:1066 for SQL_DATE_TIME_TYPES logical types.

Common situations: Mixing Beam SDK versions (e.g. pipeline built with newer Beam that added an enum constant, run with older runners); custom code constructing ConversionOptions programmatically; custom BigQueryIO forks copying this switch but extending the enum.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

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