apache/iceberg · error · 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

For non-legacy mapping, Flink TIMESTAMP(p) maps to Avro local-timestamp-millis (p<=3) or local-timestamp-micros (p<=6). Precision above 6 (nanoseconds, p=7..9) has no Avro logical-type representation, so IllegalArgumentException is thrown saying only precision less than 6 is supported.

Source

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

Solutions

1. Downgrade the column to TIMESTAMP(6) or TIMESTAMP(3) in the DDL so Avro has a matching logical type.
2. Truncate nanosecond values to microseconds before serialization.
3. Write via a format that supports nanos (e.g. Iceberg's own writer) instead of the generic Avro converter.
4. If only legacy mode exists in your version, upgrade the iceberg-flink module that adds local-timestamp-micros support.

Example fix

// before
`ts` TIMESTAMP(9)
// after
`ts` TIMESTAMP(6)

TimestampType ts = (TimestampType) logicalType;
if (!legacyMapping && ts.getPrecision() > 6) {
  throw new IllegalArgumentException("TIMESTAMP(" + ts.getPrecision() + ") exceeds Avro local-timestamp-micros; use TIMESTAMP(6) or lower");
}

try { schema = AvroSchemaConverter.convertToSchema(type, false); } catch (IllegalArgumentException e) { /* truncate precision to 6 and rebuild schema */ }

When it happens

Trigger: Calling convertToSchema with a TimestampType of precision 7-9 and legacyTimestampMapping=false; nested field conversion through fieldBuilder with a nanosecond-precision TIMESTAMP.

Common situations: Flink DDL with TIMESTAMP(9); Iceberg tables with nanosecond timestamps flowing into an Avro-based Flink sink; migrating from Spark/Flink sources that use nanos.

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

• Avro does not support TIMESTAMP type with precision: ${preci
• Avro does not support LOCAL TIMESTAMP type with precision: $
• Avro does not support TIMESTAMP type with precision: <precis
• Avro does not support TIMESTAMP type with precision: " + pre
• Unsupported type: ${type}

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