apache/flink · error · IllegalArgumentException

Avro does not support TIMESTAMP type with precision: %s, it

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(p) WITHOUT TIME ZONE to an Avro schema while legacy timestamp mapping is enabled. Legacy mapping maps TIMESTAMP to Avro's 'timestamp-millis' logical type only, so precision above 3 (millisecond) cannot be represented; the converter rejects precisions 4-9 instead of silently truncating.

Source

Thrown at flink-formats/flink-avro/src/main/java/org/apache/flink/formats/avro/typeutils/AvroSchemaConverter.java:471

                return nullable ? nullableSchema(d) : d;
            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 2f3c205e92)

Solutions

1. Declare the column as TIMESTAMP(3) (or coarser) so it fits timestamp-millis.
2. Disable legacy timestamp mapping (remove the legacy timestamp behaviour config) so precisions up to 6 map to local-timestamp-millis/micros.
3. If sub-millisecond precision is required and legacy mapping must stay, store the value as BIGINT microseconds and convert in SQL.

Example fix

-- before
col TIMESTAMP(6),

-- after (legacy timestamp mapping enabled)
col TIMESTAMP(3),

import org.apache.flink.table.types.logical.TimestampType;

void assertLegacyTimestampOk(TimestampType t) {
    if (t.getPrecision() > 3) {
        throw new IllegalArgumentException(
            "TIMESTAMP(" + t.getPrecision() + ") unsupported under legacy Avro mapping; use <= 3");
    }
}

boolean fitsLegacyAvro(TimestampType t) { return t.getPrecision() <= 3; }

When it happens

Trigger: Calling AvroSchemaConverter.convertToSchema(timestampLogicalType, legacyTimestampMapping=true) with TIMESTAMP(6)/TIMESTAMP(9); defining a table with 'avro' or 'avro-confluent-registry' format, a TIMESTAMP(6+) column, and legacy timestamp behaviour enabled (e.g. table.exec.legacy-timestamp-behaviour set for Flink 1.11/1.12 compatibility).

Common situations: Migrating jobs from old Flink versions where TIMESTAMP mapped to timestamp-millis; enabling legacy timestamp behaviour globally and then adding micro/nanosecond timestamp columns.

Related errors

• Avro does not support LOCAL TIMESTAMP type with precision: %
• Avro does not support TIMESTAMP type with precision: %s, it
• Avro does not support TIME type with precision: %s, it only
• Unsupported type: {}
• Unexpected object type for TIMESTAMP logical type. Received:

AI-assisted analysis of apache/flink@2f3c205e92 (2026-08-14). Data as JSON: /api/errors/1c681ed7fef4c814. Report an issue: GitHub.