apache/iceberg · error · IllegalArgumentException

Avro does not support LOCAL TIMESTAMP type with precision

Error message

Avro does not support LOCAL TIMESTAMP type with precision: %s, it only supports precision less than 6.

What it means

Thrown when converting a Flink TIMESTAMP (without time zone) to an Avro schema with legacyTimestampMapping=false and precision greater than 6. Avro supports localTimestampMillis and localTimestampMicros, so TIMESTAMP(7)-TIMESTAMP(9) cannot be represented. Avro simply has no nanosecond logical type.

Solutions

Cast the column to TIMESTAMP(6) or lower before writing.
If nanosecond fidelity is required, switch to a format supporting it (e.g. Parquet) instead of Avro.
Adjust the table schema or DDL to define the column as TIMESTAMP(3/6).
Truncate the value at the source (e.g. CAST(ts AS TIMESTAMP(6))).

Example fix

// before
// column defined as TIMESTAMP(9)
// after
// Flink DDL: `ts` TIMESTAMP(6)  -- fits localTimestampMicros

Defensive patterns

Strategy: validation

Validate before calling

if (logicalType instanceof TimestampType && ((TimestampType) logicalType).getPrecision() > 6) { throw new IllegalArgumentException("Cast TIMESTAMP(p) to p<=6 before Avro serialization"); }

Prevention

Cap TIMESTAMP precision at 6 when the sink is Avro.
Truncate at ingestion rather than at write time.
Switch to Parquet if nanosecond timestamps are a hard requirement.
Check upstream connectors' default precisions — some default to 9.

When it happens

Trigger: Calling AvroSchemaConverter.convertToSchema with a TimestampType of precision 7, 8, or 9 and legacyTimestampMapping=false.

Common situations: Flink tables created with TIMESTAMP(9) (default high precision in some connectors) being written to Avro-based sinks (files, Kafka with Avro encoding).

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

AI-assisted analysis of apache/iceberg@86d9c8fc54 (2026-09-12). Data as JSON: /api/errors/4261d43bae1ab726. Report an issue: GitHub.

Appendix: source

Thrown at flink/v2.3/flink/src/main/java/org/apache/iceberg/flink/formats/avro/typeutils/AvroSchemaConverter.java:500

        precision = timestampType.getPrecision();
        org.apache.avro.LogicalType avroLogicalType;
        if (legacyTimestampMapping) {
          if (precision <= 3) {
            avroLogicalType = LogicalTypes.timestampMillis();
          } else {
            throw new IllegalArgumentException(
                "Avro does not support TIMESTAMP type "
                    + "with precision: "
                    + precision
                    + ", it only supports precision less than 3.");
          }
        } else {
          if (precision <= 3) {
            avroLogicalType = LogicalTypes.localTimestampMillis();
          } else if (precision <= 6) {
            avroLogicalType = LogicalTypes.localTimestampMicros();
          } else {
            throw new IllegalArgumentException(
                "Avro does not support LOCAL TIMESTAMP type "
                    + "with precision: "
                    + precision
                    + ", it only supports precision less than 6.");
          }
        }
        Schema timestamp = avroLogicalType.addToSchema(SchemaBuilder.builder().longType());
        return nullable ? nullableSchema(timestamp) : timestamp;
      case TIMESTAMP_WITH_LOCAL_TIME_ZONE:
        if (legacyTimestampMapping) {
          throw new UnsupportedOperationException(
              "Unsupported to derive Schema for type: " + logicalType);
        } else {
          final LocalZonedTimestampType localZonedTimestampType =
              (LocalZonedTimestampType) logicalType;
          precision = localZonedTimestampType.getPrecision();
          if (precision <= 3) {
            avroLogicalType = LogicalTypes.timestampMillis();

View on GitHub (pinned to 86d9c8fc54)