apache/iceberg · error · IllegalArgumentException

Avro does not support TIMESTAMP type with precision

Error message

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

What it means

Thrown when converting a Flink TIMESTAMP_WITH_LOCAL_TIME_ZONE type to Avro with legacyTimestampMapping=false and precision greater than 6. Avro offers timestampMillis and timestampMicros only, so precisions 7-9 cannot be represented in an Avro schema.

Solutions

Cast the column to TIMESTAMP_LTZ(6) or TIMESTAMP_LTZ(3) before writing.
Change the DDL to define the column with precision 3 or 6.
Use a storage format that supports nanoseconds (e.g. Parquet) if precision 7-9 is required.
Truncate at ingestion so downstream Avro writers never see the high precision.

Example fix

// before
// `event_ts` TIMESTAMP_LTZ(9)
// after
// `event_ts` TIMESTAMP_LTZ(6)

Defensive patterns

Strategy: validation

Validate before calling

if (logicalType instanceof LocalZonedTimestampType && ((LocalZonedTimestampType) logicalType).getPrecision() > 6) { /* cast to TIMESTAMP_LTZ(3|6) before writing */ }

Prevention

Use TIMESTAMP_LTZ(3) or TIMESTAMP_LTZ(6) for Avro sinks.
Standardize event-time precision pipeline-wide.
Verify connector default precisions when defining DDL.
Prefer Parquet for nanosecond-precision event time.

When it happens

Trigger: Calling AvroSchemaConverter.convertToSchema with a LocalZonedTimestampType of precision 7-9 and legacyTimestampMapping=false.

Common situations: Flink tables with TIMESTAMP_LTZ(9) columns (common with high-precision event time) being written to Avro sinks.

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/6692fd2e3406cc52. Report an issue: GitHub.

Appendix: source

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