apache/beam · error · IllegalStateException

Unknown precision: " + this

Error message

Unknown precision: " + this

What it means

BigQueryAvroUtils contains an enum mapping Avro timestamp precision (MILLIS, MICROS, NANOS) to Instant conversion. Its toInstant default arm throws IllegalStateException when the precision enum value has no conversion branch — an internal invariant violation.

Source

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

    /** Converts an epoch value of this precision to an Instant. */
    java.time.Instant toInstant(long epochValue) {
      switch (this) {
        case MILLISECONDS:
          return java.time.Instant.ofEpochMilli(epochValue);
        case MICROSECONDS:
          {
            long seconds = Math.floorDiv(epochValue, 1_000_000L);
            long microsOfSecond = Math.floorMod(epochValue, 1_000_000L);
            return java.time.Instant.ofEpochSecond(seconds, microsOfSecond * 1_000L);
          }
        case NANOSECONDS:
          {
            long seconds = Math.floorDiv(epochValue, 1_000_000_000L);
            long nanosOfSecond = Math.floorMod(epochValue, 1_000_000_000L);
            return java.time.Instant.ofEpochSecond(seconds, nanosOfSecond);
          }
        default:
          throw new IllegalStateException("Unknown precision: " + this);
      }
    }
  }

  /**
   * Formats an Instant with minimal fractional second precision. Shows 0, 3, 6, or 9 decimal places
   * based on actual precision of the value.
   */
  @VisibleForTesting
  @SuppressWarnings("JavaInstantGetSecondsGetNano")
  static String formatDatetime(java.time.Instant instant) {
    String dateTime = DATE_TIME_FORMATTER.format(instant);
    int nanos = instant.getNano();

    if (nanos == 0) {
      return dateTime;
    } else if (nanos % 1_000_000 == 0) {
      return dateTime + String.format(".%03d", nanos / 1_000_000);

View on GitHub (pinned to 12126d8942)

Solutions

1. Upgrade or align Apache Beam versions so code and data precision enums match
2. Ensure Avro input files only use MILLIS/MICROS/NANOS timestamp precision
3. Report a bug if a supported precision still hits the default branch

Example fix

// before
switch (precision) { case MILLIS: ...; } // NANOS missing
// after
switch (precision) { case MILLIS: ...; case MICROS: ...; case NANOS: ...; }

try { Instant t = precision.toInstant(epochValue); } catch (IllegalStateException e) { /* fall back to millis precision */ }

When it happens

Trigger: Calling toInstant on the precision enum when a new Avro logical type precision is added but the conversion switch is not updated; or reflective/unexpected enum value at runtime.

Common situations: Beam version mismatches where an Avro file carries a precision enum value the loaded Beam code does not know; practically rare because the enum set is closed.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

• Unexpected mode: " + mode
• Unknown mode: " + mode
• Extract file timestamp failed: got file timestamp == 0.
• Thread pool not initialized for UUID:
• Processing elements map not initialized for UUID:

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