apache/seatunnel · warning

The timestamp_tz column {} type timestamp({}) is out of rang

Error message

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

What it means

Warning from OracleTypeConverter.reconvert for timestamp-with-local-time-zone columns: the column's fractional-second scale exceeds MAX_TIMESTAMP_SCALE, so the mapped ORACLE_TIMESTAMP_WITH_LOCAL_TIME_ZONE type is created with the clamped scale. The message reports original timestamp(scale), the max, and the converted timestamp(max).

Source

Thrown at seatunnel-connectors-v2/connector-jdbc/src/main/java/org/apache/seatunnel/connectors/seatunnel/jdbc/internal/dialect/oracle/OracleTypeConverter.java:436

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

View on GitHub (pinned to cf67b549a7)

Solutions

1. Normalize the column upstream to ≤9 fractional digits before writing to Oracle.
2. Pre-create the Oracle table with TIMESTAMP(9) WITH LOCAL TIME ZONE and load into it.
3. If higher precision is required, Oracle cannot represent it — serialize as string or move to a store that supports it.
4. Accept the clamp if microsecond precision suffices.

Example fix

// before
ev_tztz timestamp(scale=12) → TIMESTAMP(12) WITH LOCAL TIME ZONE
// after (upstream)
ev_tztz = date_trunc(ev_tztz, 'nanoseconds'); → TIMESTAMP(9) WITH LOCAL TIME ZONE

if (column.getScale() != null && column.getScale() > 9) {
  // normalize timestamptz upstream: date_trunc(ts, 'nanoseconds')
}

boolean isOracleSafeTzTimestamp(Integer scale) {
  return scale == null || (scale >= 0 && scale <= 9);
}

When it happens

Trigger: reconvert on a Column mapped to ORACLE_TIMESTAMP_WITH_LOCAL_TIME_ZONE where column.getScale() > MAX_TIMESTAMP_SCALE, during sink schema creation for Oracle.

Common situations: Syncing high-precision timestamptz columns (e.g. from Postgres/analytic stores) into Oracle with auto table creation; pipelines that preserved excessive scale from earlier conversions.

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 timestamp column {} type timestamp({}) is out of range,
• The timestamp_tz column {} type datetime_tz({}) is out of ra
• The decimal column {} type decimal({},{}) is out of range, w
• The timestamp column {} type timestamp({}) is out of range,
• The scale of timestamp type is larger than {}, it will be tr

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