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

Change the TIME column precision to TIME(3) or lower before conversion (e.g. CAST(col AS TIME(3)) or alter the table DDL).

apache/iceberg · error · IllegalArgumentException

Avro does not support TIME type with precision: <precision>,

Error message

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

What it means

AvroSchemaConverter.convertToSchema maps Flink logical types to Avro schemas. Avro's time logical types (timeMillis/timeMicros) cannot represent Flink TIME with precision greater than 3 (i.e., microsecond) fractional seconds, so the converter rejects it with IllegalArgumentException to avoid silent precision loss.

Source

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

            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
                  + ", it only supports precision less than 3.");
        }
        // use int to represents Time, we only support millisecond when deserialization
        Schema time = LogicalTypes.timeMillis().addToSchema(SchemaBuilder.builder().intType());
        return nullable ? nullableSchema(time) : time;
      case DECIMAL:
        DecimalType decimalType = (DecimalType) logicalType;
        // store BigDecimal as byte[]
        Schema decimal =
            LogicalTypes.decimal(decimalType.getPrecision(), decimalType.getScale())
                .addToSchema(SchemaBuilder.builder().bytesType());
        return nullable ? nullableSchema(decimal) : decimal;
      case ROW:
        RowType rowType = (RowType) logicalType;
        List<String> fieldNames = rowType.getFieldNames();
        // we have to make sure the record name is different in a Schema

View on GitHub (pinned to 86d9c8fc54)

Solutions

Change the TIME column precision to TIME(3) or lower before conversion (e.g. CAST(col AS TIME(3)) or alter the table DDL).
If you control the schema source, declare the Flink type as TIMESTAMP(3) instead of higher-precision TIME.
Preprocess the stream with a Map that converts Time to a supported type (e.g. Integer millis or LocalTime truncated to millis) and adjust the schema accordingly.

Example fix

// before: TIME(6) column fails
Schema s = AvroSchemaConverter.convertToSchema(new TimeType(6));

// after: use millisecond precision
Schema s = AvroSchemaConverter.convertToSchema(new TimeType(3));

Defensive patterns

Strategy: validation

Validate before calling

// check TIME precision before conversion
if (logicalType instanceof TimeType && ((TimeType) logicalType).getPrecision() > 3) {
    throw new IllegalArgumentException("TIME precision must be <= 3 for Avro: " + logicalType);
}

Type guard

boolean isAvroSafeTime(LogicalType t) {
    return !(t instanceof TimeType) || ((TimeType) t).getPrecision() <= 3;
}

Prevention

Declare TIME columns with explicit precision TIME(3) or lower
Review table DDL for implicit high-precision time types
Add a schema pre-check step before Avro serialization in pipelines
Prefer TIMESTAMP(3) for microsecond-precision needs with explicit truncation

When it happens

Trigger: Calling AvroSchemaConverter.convertToSchema (directly or via fieldBuilder when converting a ROW) with a Flink TimeType whose precision is > 3, e.g. TIME(6).

Common situations: Tables or DataStreams defined with TIME(6) or other microsecond-precision TIME columns (Flink default DDL without explicit precision can inherit higher precision), then serialized with the Avro format or written via Avro-based 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/b2f9f5e645d099ea. Report an issue: GitHub.