What causes "Avro does not support TIMESTAMP type with precision: , it only supports precision less than 6." in apache/iceberg?

Declare the column as TIMESTAMP_LTZ(6) or lower in the Flink DDL.

apache/iceberg · error · IllegalArgumentException

Avro does not support TIMESTAMP type with precision: <precis

Error message

Avro does not support TIMESTAMP type with precision: <precision>, it only supports precision less than 6.

What it means

When converting TIMESTAMP_WITH_LOCAL_TIME_ZONE to Avro with legacyTimestampMapping=false, precision <= 3 maps to timestampMillis and <= 6 to timestampMicros; precision above 6 (7-9) exceeds what Avro instant logical types support, so IllegalArgumentException "...it only supports precision less than 6" is thrown.

Source

Thrown at flink/v1.20/flink/src/main/java/org/apache/iceberg/flink/formats/avro/typeutils/AvroSchemaConverter.java:522

                    + ", 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();
          } else if (precision <= 6) {
            avroLogicalType = LogicalTypes.timestampMicros();
          } else {
            throw new IllegalArgumentException(
                "Avro does not support TIMESTAMP type "
                    + "with precision: "
                    + precision
                    + ", it only supports precision less than 6.");
          }
          timestamp = avroLogicalType.addToSchema(SchemaBuilder.builder().longType());
          return nullable ? nullableSchema(timestamp) : timestamp;
        }
      case DATE:
        // use int to represents Date
        Schema date = LogicalTypes.date().addToSchema(SchemaBuilder.builder().intType());
        return nullable ? nullableSchema(date) : date;
      case TIME_WITHOUT_TIME_ZONE:
        precision = ((TimeType) logicalType).getPrecision();
        if (precision > 3) {
          throw new IllegalArgumentException(
              "Avro does not support TIME type with precision: "
                  + precision

View on GitHub (pinned to 86d9c8fc54)

Solutions

Declare the column as TIMESTAMP_LTZ(6) or lower in the Flink DDL.
Cast before conversion: CAST(ts AS TIMESTAMP_LTZ(6)).
If nanosecond precision is essential, store as BIGINT epoch nanos since Avro instant logical types cap at micros.
Confirm the value truly needs >micros precision; most systems silently truncate anyway.

Example fix

// before
Schema s = AvroSchemaConverter.convertToSchema(new LocalZonedTimestampType(9), false); // throws
// after
Schema s = AvroSchemaConverter.convertToSchema(new LocalZonedTimestampType(6), false); // timestampMicros

Defensive patterns

Strategy: validation

Validate before calling

LocalZonedTimestampType ts = (LocalZonedTimestampType) logicalType;
if (!legacyMapping && ts.getPrecision() > 6) {
  throw new IllegalStateException("TIMESTAMP_LTZ(" + ts.getPrecision() + ") exceeds Avro micros limit; use <= 6");
}

Try / catch

try {
  Schema s = AvroSchemaConverter.convertToSchema(ltzType, false);
} catch (IllegalArgumentException e) {
  if (e.getMessage().contains("TIMESTAMP type") && e.getMessage().contains("less than 6")) {
    s = AvroSchemaConverter.convertToSchema(new LocalZonedTimestampType(6), false);
  } else throw e;
}

Prevention

Cap TIMESTAMP_LTZ precision at 6 in DDL; Avro instants max at micros.
CAST TIMESTAMP_LTZ(7-9) down in the pipeline before schema conversion.
Store sub-microsecond values as separate BIGINT fields if needed.

When it happens

Trigger: AvroSchemaConverter.convertToSchema(LogicalType, boolean) — directly or via nested fieldBuilder — with a LocalZonedTimestampType whose precision is 7-9, e.g. TIMESTAMP_LTZ(9).

Common situations: Nanosecond-precision TIMESTAMP_LTZ columns from sources like Kafka connect or CDC; Flink type inference producing TIMESTAMP_LTZ(9) by default for certain expressions; DDL copying source precision without reduction.

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/387e9df3ec25a8d3. Report an issue: GitHub.