apache/seatunnel · warning

The timestamp column {} type timestamp({}) is out of range,

Error message

The timestamp column {} type timestamp({}) is out of range, which exceeds the maximum scale of {}, it will be converted to timestamp({})

What it means

When converting a TIMESTAMP column to the Phoenix type, a scale greater than MAX_TIMESTAMP_SCALE cannot be represented, so the converter logs this warning and clamps the timestamp scale to MAX_TIMESTAMP_SCALE. Fractional-second digits beyond the limit are truncated when data is written.

Source

Thrown at seatunnel-connectors-v2/connector-jdbc/src/main/java/org/apache/seatunnel/connectors/seatunnel/jdbc/internal/dialect/phoenix/PhoenixTypeConverter.java:310

                                    + "it will be converted to time({})",
                            column.getName(),
                            column.getScale(),
                            MAX_SCALE,
                            timeScale);
                }
                if (timeScale != null && timeScale > 0) {
                    builder.columnType(String.format("%s(%s)", PHOENIX_TIME, timeScale));
                } else {
                    builder.columnType(PHOENIX_TIME);
                }
                builder.dataType(PHOENIX_TIME);
                builder.scale(timeScale);
                break;
            case TIMESTAMP:
                Integer timestampScale = column.getScale();
                if (timestampScale != null && timestampScale > MAX_TIMESTAMP_SCALE) {
                    timestampScale = MAX_TIMESTAMP_SCALE;
                    log.warn(
                            "The timestamp column {} type timestamp({}) is out of range, "
                                    + "which exceeds the maximum scale of {}, "
                                    + "it will be converted to timestamp({})",
                            column.getName(),
                            column.getScale(),
                            MAX_TIMESTAMP_SCALE,
                            timestampScale);
                }
                if (timestampScale != null && timestampScale > 0) {
                    builder.columnType(String.format("%s(%s)", PHOENIX_TIMESTAMP, timestampScale));
                } else {
                    builder.columnType(PHOENIX_TIMESTAMP);
                }
                builder.dataType(PHOENIX_TIMESTAMP);
                builder.scale(timestampScale);
                break;
            case ARRAY:
                ArrayType arrayType = (ArrayType) column.getDataType();

View on GitHub (pinned to cf67b549a7)

Solutions

1. Lower the timestamp scale in the source/catalog to within MAX_TIMESTAMP_SCALE.
2. CAST the column upstream, e.g. CAST(ts AS TIMESTAMP(3)), before the Phoenix sink.
3. Check the warning to confirm the applied precision suffices for your data.
4. Choose a sink supporting nanosecond precision if truncation is unacceptable.

Example fix

// before
catalogColumn = CatalogColumn.of("ts", TimestampType(9));
// after
catalogColumn = CatalogColumn.of("ts", TimestampType(3));

Integer scale = col.getScale();
if (col.getDataType() instanceof TimestampType && scale != null && scale > maxTimestampScale) {
    col = CatalogColumn.of(col.getName(), new TimestampType(maxTimestampScale), col.isNullable(), col.getDefaultValue());
}

boolean fitsPhoenixTimestampScale(CatalogColumn c) {
    Integer s = c.getScale();
    return !(c.getDataType() instanceof TimestampType) || s == null || s <= 3;
}

When it happens

Trigger: PhoenixTypeConverter.reconvert() on a CatalogColumn of type TIMESTAMP with a non-null scale exceeding MAX_TIMESTAMP_SCALE (e.g. TIMESTAMP(9) nanosecond timestamps).

Common situations: Nanosecond-precision timestamps from sources like certain databases or event streams being sunk to Phoenix, which caps fractional-second precision.

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

• The decimal column {} type decimal({},{}) is out of range, w
• The decimal column {} type decimal({},{}) is out of range, w
• The time column {} type time({}) is out of range, which exce
• The scale of timestamp type is larger than {}, it will be tr
• COMMON-17

AI-assisted analysis of apache/seatunnel@cf67b549a7 (2026-09-10). Data as JSON: /api/errors/47908f85d874b68a. Report an issue: GitHub.