apache/iceberg · error · IllegalArgumentException

Avro does not support TIME type with precision: " +…

Error message

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

What it means

Avro's time-millis logical type only supports millisecond precision, so when converting a Flink TIME type the converter rejects precision greater than 3 with IllegalArgumentException. TIME(0..3) maps to LogicalTypes.timeMillis stored as an int.

Solutions

Change the column to TIME(3) (or lower) in the table/DDL definition.
Cast the TIME column to TIME(3) before conversion, e.g. CAST(col AS TIME(3)).
Truncate precision at the source (UDF/connector) so TIME columns never exceed millisecond precision.

Example fix

// before
CREATE TABLE t (tm TIME(6));
// after
CREATE TABLE t (tm TIME(3));

Defensive patterns

Strategy: validation

Validate before calling

if (type instanceof TimeType) {
  Preconditions.checkArgument(((TimeType) type).getPrecision() <= 3,
      "Avro supports TIME precision <= 3, got " + ((TimeType) type).getPrecision());
}

Type guard

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

Try / catch

try {
  Schema s = AvroSchemaConverter.convertToSchema(logicalType, rowName);
} catch (IllegalArgumentException e) {
  // cast TIME to TIME(3) upstream or fail fast with schema guidance
}

Prevention

Use TIME(3) (the max Avro-compatible precision) in table DDL
Cast TIME columns in SQL before they reach serialization
Add a schema-compat preflight check when schemas come from external sources

When it happens

Trigger: Calling AvroSchemaConverter.convertToSchema with a Flink TimeType whose precision is > 3 (directly, or via a RowType field processed by fieldBuilder).

Common situations: Flink DDL declaring TIME(6) or TIME(9) (some connectors/UDFs emit high-precision TIME), then running it through Avro-based serialization (e.g. Avro encoding of Flink state or data).

Related errors

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

Appendix: source

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