apache/seatunnel · warning

The timestamp_tz column

Error message

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

What it means

Warning from XuguTypeConverter.reconvert when a TIMESTAMP WITH TIME ZONE column's scale exceeds XuGu's MAX_TIMESTAMP_SCALE for XUGU_TIMESTAMP_WITH_TIME_ZONE. The scale is clamped to the maximum; conversion continues and only this warning is emitted.

Solutions

1. Cast the source column to a lower-precision timestamptz (e.g. TIMESTAMPTZ(3)) before the sink.
2. Accept the automatic scale clamp and validate the rounded values.
3. Pre-create the XuGu target column with an allowed scale.

Example fix

// before: timestamptz(9)
// after
SQL: CAST(tz_col AS TIMESTAMPTZ(6)) AS tz_col

if (col.getSqlType() == SqlType.TIMESTAMP_WITH_TIME_ZONE && col.getColumnScale() > MAX_TIMESTAMP_SCALE) {
    col = col.copy().setColumnScale(MAX_TIMESTAMP_SCALE).build();
}

boolean withinTzTimestampScale(ColumnType c) { return c.getScale() == null || c.getScale() <= MAX_TIMESTAMP_SCALE; }

When it happens

Trigger: Catalog sink write to XuGu of a timestamp_tz column with scale > MAX_TIMESTAMP_SCALE, e.g. timestamptz(9) from PostgreSQL.

Common situations: Syncing PostgreSQL timestamptz or other tz-aware high-precision timestamps into XuGu; auto table creation deriving scale from the source dialect.

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 time column type time( ) is out of range, which exceeds…
• The timestamp column
• COMMON-17
• COMMON-19
• The timestamp_tz column

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

Appendix: source

Thrown at seatunnel-connectors-v2/connector-jdbc/src/main/java/org/apache/seatunnel/connectors/seatunnel/jdbc/internal/dialect/xugu/XuguTypeConverter.java:392

                                        + "it will be converted to timestamp({})",
                                column.getName(),
                                column.getScale(),
                                MAX_TIMESTAMP_SCALE,
                                timestampScale);
                    }
                    builder.columnType(String.format("TIMESTAMP(%s)", timestampScale));
                    builder.scale(timestampScale);
                }
                builder.dataType(XUGU_TIMESTAMP);
                break;
            case TIMESTAMP_TZ:
                if (column.getScale() == null || column.getScale() <= 0) {
                    builder.columnType(XUGU_TIMESTAMP_WITH_TIME_ZONE);
                } else {
                    int timestampTzScale = column.getScale();
                    if (column.getScale() > MAX_TIMESTAMP_SCALE) {
                        timestampTzScale = MAX_TIMESTAMP_SCALE;
                        log.warn(
                                "The timestamp_tz column {} type timestamp_tz({}) is out of"
                                        + " range, which exceeds the maximum scale of {}, "
                                        + "it will be converted to timestamp_tz({})",
                                column.getName(),
                                column.getScale(),
                                MAX_TIMESTAMP_SCALE,
                                timestampTzScale);
                    }
                    builder.columnType(
                            String.format("TIMESTAMP(%s) WITH TIME ZONE", timestampTzScale));
                    builder.scale(timestampTzScale);
                }
                builder.dataType(XUGU_TIMESTAMP_WITH_TIME_ZONE);
                break;
            default:
                throw CommonError.convertToConnectorTypeError(
                        DatabaseIdentifier.XUGU,
                        column.getDataType().getSqlType().name(),

View on GitHub (pinned to cf67b549a7)