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 3.

What it means

Thrown when converting a Flink TIMESTAMP (without time zone) logical type to an Avro schema with legacyTimestampMapping=true and precision greater than 3. Avro's legacy mapping only offers timestampMillis, so precisions above 3 (e.g. TIMESTAMP(6)) cannot be represented. A higher precision requires the non-legacy mapping, which supports micros.

Solutions

  1. Disable legacy timestamp mapping (legacyTimestampMapping=false) so micros are used.
  2. Or cast the column to TIMESTAMP(3) to fit timestampMillis.
  3. Update table/connector config to remove the legacy-mapping flag.
  4. Align source schema precision with the sink before writing.

Example fix

// before
Schema s = AvroSchemaConverter.convertToSchema(timestampType, true); // legacy, precision 6
// after
Schema s = AvroSchemaConverter.convertToSchema(timestampType, false); // localTimestampMicros supported
Defensive patterns

Strategy: validation

Validate before calling

if (logicalType instanceof TimestampType && ((TimestampType) logicalType).getPrecision() > 3 && legacyTimestampMapping) { /* cast column to TIMESTAMP(3) or disable legacy mapping */ }

Prevention

When it happens

Trigger: Calling AvroSchemaConverter.convertToSchema(LogicalType, boolean) (directly or via fieldBuilder) with a TimestampType whose precision is 4-9 while legacyTimestampMapping is true.

Common situations: Tables defined with TIMESTAMP(6) or TIMESTAMP(9) being written to Avro with legacy timestamp mapping enabled (often a leftover config from older Flink versions).

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/3f9fc4dbc816dd53. Report an issue: GitHub.

Appendix: source

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