apache/beam · error · IllegalArgumentException

Unsupported timestamp precision for Storage Read API:

Error message

Unsupported timestamp precision for Storage Read API: 

What it means

setArrowTimestampPrecision maps Beam's TimestampPrecision enum onto the Arrow PicosTimestampPrecision proto used by the Storage Read API. The switch handles MICROS, NANOS and PICOS; any other value falls through to default and throws IllegalArgumentException. This is an exhaustive-enum guard against unexpected precision values.

Solutions

1. Pass only TimestampPrecision.MICROS, NANOS, or PICOS when configuring withTimestampPrecision/withPicosTimestampPrecision
2. Check that beam-sdks-java-io-google-cloud-platform and google-cloud-bigquery-storage versions are aligned
3. Wrap source construction in code that validates the configured precision against EnumSet.of(MICROS, NANOS, PICOS) before building the source

Example fix

// before
TimestampPrecision p = TimestampPrecision.valueOf(userInput); // may be unknown
// after
TimestampPrecision p = TimestampPrecision.valueOf(userInput);
if (p != TimestampPrecision.MICROS && p != TimestampPrecision.NANOS && p != TimestampPrecision.PICOS) {
  throw new IllegalArgumentException("Precision must be MICROS, NANOS or PICOS: " + userInput);
}

static final Set<TimestampPrecision> SUPPORTED =
    EnumSet.of(TimestampPrecision.MICROS, TimestampPrecision.NANOS, TimestampPrecision.PICOS);
if (!SUPPORTED.contains(precision)) throw new IllegalArgumentException("Unsupported precision: " + precision);

boolean isSupportedPrecision(TimestampPrecision p) {
  return p == TimestampPrecision.MICROS || p == TimestampPrecision.NANOS || p == TimestampPrecision.PICOS;
}

try {
  source = source.withTimestampPrecision(precision);
} catch (IllegalArgumentException e) {
  precision = TimestampPrecision.NANOS; // safe fallback
  source = source.withTimestampPrecision(precision);
}

When it happens

Trigger: Calling setPicosTimestampPrecision (indirectly via Beam source configuration) with a TimestampPrecision value that is not MICROS/NANOS/PICOS — only possible via a null-unsafe custom enum, a differently-shipped TimestampPrecision enum version, or reflection-built values.

Common situations: Version skew where a new TimestampPrecision constant was added in one library version but this Beam switch predates it; user code passing its own precision abstraction misinterpreted as Beam's 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

• BigQuery data contained value
• BigQuery storage source must be split before reading
• change_function must be 'CHANGES' or 'APPENDS', got
• Converting BigQuery type to Beam type is unsupported
• Invalid create disposition

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

Appendix: source

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

    }
  }

  private static void setArrowTimestampPrecision(
      ReadSession.TableReadOptions.Builder tableReadOptionsBuilder,
      TimestampPrecision timestampPrecision) {
    ArrowSerializationOptions.PicosTimestampPrecision precision;
    switch (timestampPrecision) {
      case MICROS:
        precision = ArrowSerializationOptions.PicosTimestampPrecision.TIMESTAMP_PRECISION_MICROS;
        break;
      case NANOS:
        precision = ArrowSerializationOptions.PicosTimestampPrecision.TIMESTAMP_PRECISION_NANOS;
        break;
      case PICOS:
        precision = ArrowSerializationOptions.PicosTimestampPrecision.TIMESTAMP_PRECISION_PICOS;
        break;
      default:
        throw new IllegalArgumentException(
            "Unsupported timestamp precision for Storage Read API: " + timestampPrecision);
    }
    tableReadOptionsBuilder.setArrowSerializationOptions(
        ArrowSerializationOptions.newBuilder().setPicosTimestampPrecision(precision));
  }

  private static void setAvroTimestampPrecision(
      ReadSession.TableReadOptions.Builder tableReadOptionsBuilder,
      TimestampPrecision timestampPrecision) {
    AvroSerializationOptions.PicosTimestampPrecision precision;
    switch (timestampPrecision) {
      case MICROS:
        precision = AvroSerializationOptions.PicosTimestampPrecision.TIMESTAMP_PRECISION_MICROS;
        break;
      case NANOS:
        precision = AvroSerializationOptions.PicosTimestampPrecision.TIMESTAMP_PRECISION_NANOS;
        break;
      case PICOS:

View on GitHub (pinned to 12126d8942)