apache/flink · error · IllegalArgumentException

Time unit not recognized

Error message

Time unit not recognized

What it means

TimestampWriter.convertInt64ToLong switches on the writer's configured timeUnit (NANOS, MICROS, MILLIS) to scale a millisecond-based value. Any other value hits the default and throws IllegalArgumentException('Time unit not recognized') - in practice only reachable if the constructor was given an invalid unit.

Source

Thrown at flink-formats/flink-parquet/src/main/java/org/apache/flink/formats/parquet/row/ParquetRowDataWriter.java:540

    private void writeTimestamp(RecordConsumer recordConsumer, TimestampData timestampData) {
        if (useInt64) {
            recordConsumer.addLong(timestampToInt64(timestampData));
        } else {
            recordConsumer.addBinary(timestampToInt96(timestampData));
        }
    }

    private Long convertInt64ToLong(long mills, long nanosOfMillisecond) {
        switch (timeUnit) {
            case NANOS:
                return mills * NANOS_PER_MILLISECOND + nanosOfMillisecond;
            case MICROS:
                return mills * MICROS_PER_MILLISECOND + nanosOfMillisecond / NANOS_PER_MICROSECONDS;
            case MILLIS:
                return mills;
            default:
                throw new IllegalArgumentException("Time unit not recognized");
        }
    }

    private Long timestampToInt64(TimestampData timestampData) {
        long mills = 0L;
        long nanosOfMillisecond = 0L;
        if (utcTimestamp) {
            mills = timestampData.getMillisecond();
            nanosOfMillisecond = timestampData.getNanoOfMillisecond();
        } else {
            Timestamp timestamp = timestampData.toTimestamp();
            mills = timestamp.getTime();
            nanosOfMillisecond = timestamp.getNanos() % NANOS_PER_MILLISECOND;
        }
        return convertInt64ToLong(mills, nanosOfMillisecond);
    }

    private Binary timestampToInt96(TimestampData timestampData) {

View on GitHub (pinned to 2f3c205e92)

Solutions

1. Use standard timestamp precisions (0-3 -> MILLIS, 4-6 -> MICROS, 7-9 -> NANOS) in the table schema
2. If constructing the writer manually, pass exactly one of TimeUnit.NANOS/MICROS/MILLIS
3. If hit after a parquet dependency upgrade, check for new TimeUnit enum values and pin the previous version

Example fix

// before
table DDL: ts TIMESTAMP(12)  -- unsupported precision mapping

// after
table DDL: ts TIMESTAMP(6)   -- MICROS, supported

int precision = ((TimestampType) type).getPrecision();
if (precision < 0 || precision > 9) throw new IllegalArgumentException("timestamp precision must be 0-9");

When it happens

Trigger: Constructing a TimestampWriter/ParquetRowDataWriter with a timestamp precision that maps to an unsupported TimeUnit, or passing null/unknown TimeUnit for TIMESTAMP columns.

Common situations: Very rare; a library-internal invariant break, e.g. a new time unit enum value in parquet-common not covered here, or custom code constructing the writer directly with a bogus unit.

Related errors

• JAR file is not a file: {}
• Missing JobId
• Unsupported type: {}
• Unsupported type: {}
• Invalid time unit:

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