apache/iceberg · error · IllegalArgumentException

Avro does not support TIMESTAMP type with precision: " + pre

Error message

Avro does not support TIMESTAMP type with precision: " + precision + ", it only supports precision less than 3.

What it means

When converting a Flink TIMESTAMP(p) logical type to an Avro schema (convertToSchema), legacy timestamp mapping only supports timestamp-millis, i.e. precision <= 3. Higher precision (micros/nanos) has no legacy Avro representation, so IllegalArgumentException is thrown stating Avro only supports precision less than (or equal to) 3 in this mode.

Source

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

        return nullable ? nullableSchema(doubleSchema) : doubleSchema;
      case CHAR:
      case VARCHAR:
        Schema str = SchemaBuilder.builder().stringType();
        return nullable ? nullableSchema(str) : str;
      case BINARY:
      case VARBINARY:
        Schema binary = SchemaBuilder.builder().bytesType();
        return nullable ? nullableSchema(binary) : binary;
      case TIMESTAMP_WITHOUT_TIME_ZONE:
        // use long to represents Timestamp
        final TimestampType timestampType = (TimestampType) logicalType;
        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.");
          }
        }

View on GitHub (pinned to 86d9c8fc54)

Solutions

  1. Set legacyTimestampMapping=false so precision<=6 maps to localTimestampMicros and 9 to nanos where supported.
  2. Reduce the Flink TIMESTAMP precision to 3 (TIMESTAMP(3)) if legacy mode must stay enabled.
  3. Truncate/convert timestamps to millis before writing when on the legacy path.
  4. Update the table/connector config so the timestamp mapping flag matches the actual column precision.

Example fix

// before
TIMESTAMP(6) with legacyTimestampMapping = true
// after
TIMESTAMP(3) with legacyTimestampMapping = true  // or keep TIMESTAMP(6) and set legacyTimestampMapping = false
Defensive patterns

Strategy: validation

Validate before calling

TimestampType ts = (TimestampType) logicalType;
if (legacyMapping && ts.getPrecision() > 3) {
  throw new IllegalArgumentException("TIMESTAMP(" + ts.getPrecision() + ") requires legacyTimestampMapping=false");
}

Try / catch

try { schema = AvroSchemaConverter.convertToSchema(type, legacy); } catch (IllegalArgumentException e) { /* retry with legacy=false or degrade precision */ }

Prevention

When it happens

Trigger: Calling AvroSchemaConverter.convertToSchema with a TimestampType whose precision is > 3 while legacyTimestampMapping=true (the legacy path uses LogicalTypes.timestampMillis).

Common situations: See trigger scenarios.

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/788eba0ace013425. Report an issue: GitHub.