apache/beam · error · IllegalArgumentException

DateTime64 precision must be in [0, 9], got

Error message

DateTime64 precision must be in [0, 9], got 

What it means

Thrown by TableSchema.ColumnType.dateTime64(int) when the requested DateTime64 precision is outside the ClickHouse-valid range [0, 9]. Precision sets the number of sub-second digits (0=seconds, 3=millis, 9=nanos); other values cannot map to a valid ClickHouse type.

Solutions

1. Validate or clamp precision to [0, 9] before calling dateTime64(precision).
2. Choose 9 (nanoseconds) if the source has finer resolution, truncating the source data.
3. Fix the schema-string parser to accept only valid precision values.
4. Ensure unset precision falls back to dateTime64() (default) rather than a sentinel.

Example fix

// before
ColumnType t = TableSchema.ColumnType.dateTime64(12); // out of range
// after
int p = Math.min(9, Math.max(0, parsedPrecision));
ColumnType t = TableSchema.ColumnType.dateTime64(p);

int validDateTime64Precision(int precision) {
  if (precision < 0 || precision > 9) {
    throw new IllegalArgumentException("DateTime64 precision must be in [0, 9]: " + precision);
  }
  return precision;
}
// call: TableSchema.ColumnType.dateTime64(validDateTime64Precision(p))

try {
  ColumnType t = TableSchema.ColumnType.dateTime64(parsedPrecision);
} catch (IllegalArgumentException e) {
  if (e.getMessage() != null && e.getMessage().contains("precision must be in [0, 9]")) {
    LOG.warn("Invalid DateTime64 precision {}, falling back to default", parsedPrecision);
    return TableSchema.ColumnType.dateTime64();
  }
  throw e;
}

When it happens

Trigger: Calling ColumnType.dateTime64(precision) with a negative value, a value > 9, or precision taken unvalidated from a parsed schema string (e.g. DateTime64(12)).

Common situations: Parsing ClickHouse DDL where precision came from an unchecked regex group; copying DateTime64(12) definitions from other systems; defaulting an unset precision field to a sentinel like -1.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• Decimal precision must be in [1, 76], got
• Decimal scale must be in [0, ], got
• Encountered an empty schema
• Expected input Schema to have a 'payload' (STRING) or…
• Failed to get table schema for table:

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

Appendix: source

Thrown at sdks/java/io/clickhouse/src/main/java/org/apache/beam/sdk/io/clickhouse/TableSchema.java:317

    public static ColumnType fixedString(int size) {
      return ColumnType.builder()
          .typeName(TypeName.FIXEDSTRING)
          .nullable(false)
          .fixedStringSize(size)
          .build();
    }

    /** Default {@code DateTime64} precision in ClickHouse. */
    public static final int DEFAULT_DATETIME64_PRECISION = 3;

    /** Returns a {@code DateTime64} type with ClickHouse's default precision of 3. */
    public static ColumnType dateTime64() {
      return dateTime64(DEFAULT_DATETIME64_PRECISION);
    }

    public static ColumnType dateTime64(int precision) {
      if (precision < 0 || precision > 9) {
        throw new IllegalArgumentException(
            "DateTime64 precision must be in [0, 9], got " + precision);
      }
      return ColumnType.builder()
          .typeName(TypeName.DATETIME64)
          .nullable(false)
          .precision(precision)
          .build();
    }

    /** Default {@code Decimal} precision in ClickHouse when none is specified. */
    public static final int DEFAULT_DECIMAL_PRECISION = 10;

    /** Default {@code Decimal} scale in ClickHouse when none is specified. */
    public static final int DEFAULT_DECIMAL_SCALE = 0;

    /**
     * Returns a {@code Decimal(precision, scale)} type.
     *

View on GitHub (pinned to 12126d8942)