apache/iceberg · error · java.lang.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 timeMillis logical type has millisecond resolution and the converter stores TIME as int. Flink TIME(p) with p > 3 cannot be represented, so conversion fails with IllegalArgumentException instead of losing precision.

Solutions

Declare the TIME column with precision <= 3 (e.g. TIME(0) or TIME(3))
Cast the column to TIME(3) before serialization
Store the time as string or BIGINT manually if higher precision is needed

Example fix

// before
columns: TIME(6)
Schema avro = AvroSchemaConverter.convertToSchema(rowType, "rec", false);
// after
columns: TIME(3)
Schema avro = AvroSchemaConverter.convertToSchema(rowType, "rec", false);

Defensive patterns

Strategy: validation

Validate before calling

if (timeType.getPrecision() > 3) {
  throw new IllegalArgumentException("TIME precision must be <= 3 for Avro; got " + timeType.getPrecision());
}

Prevention

Declare TIME columns as TIME(0) or TIME(3)
Cast high-precision TIME to TIME(3) at the sink boundary
Check precision defaults of the upstream framework that generates the DDL

When it happens

Trigger: Calling AvroSchemaConverter.convertToSchema on a row containing TIME(4) through TIME(9).

Common situations: Flink DDL with high-precision TIME columns mapped to an Avro sink; defaults changed from TIME(0)/TIME(3) to higher precision by framework code.

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/81a20f4e9fdd7fa1. Report an issue: GitHub.

Appendix: source

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