apache/iceberg · error · java.lang.IllegalArgumentException

Avro does not support LOCAL TIMESTAMP type with precision

Error message

Avro does not support LOCAL TIMESTAMP type with precision: ${precision}, it only supports precision less than 6.

What it means

When converting a Flink TIMESTAMP(p) to Avro without legacy mapping, precision up to 6 maps to localTimestampMicros; anything above 6 has no Avro local-timestamp logical type, so the converter rejects it rather than truncate silently.

Solutions

Declare the column as TIMESTAMP(6) or lower so it maps to localTimestampMicros
Cast the timestamp to TIMESTAMP(6) before conversion
If nanosecond precision is required, serialize via a different format (e.g. Arrow/Parquet) instead of Avro

Example fix

// before
columns: TIMESTAMP(9)
Schema avro = AvroSchemaConverter.convertToSchema(rowType, "record", false);
// after
columns: TIMESTAMP(6)
Schema avro = AvroSchemaConverter.convertToSchema(rowType, "record", false);

Defensive patterns

Strategy: validation

Validate before calling

if (timestampType.getPrecision() > 6) {
  throw new IllegalArgumentException("Avro local timestamp supports precision <= 6; got " + timestampType.getPrecision());
}

Prevention

Cap TIMESTAMP precision at 6 for Avro pipelines
Avoid TIMESTAMP(9); Flink's max precision exceeds Avro's logical-type limits
Document format precision limits in your schema conventions

When it happens

Trigger: Calling AvroSchemaConverter.convertToSchema on a type containing TIMESTAMP(7) through TIMESTAMP(9) with legacyTimestampMapping=false.

Common situations: Flink DDL using the maximum TIMESTAMP(9) precision being written through an Avro serialization path; schema evolution where a column's precision was increased beyond micros.

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/6be48a4807d67e0d. Report an issue: GitHub.

Appendix: source

Thrown at flink/v2.1/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)