apache/seatunnel · error · IllegalArgumentException

Unable to convert TIMESTAMP_TZ from String value: '${value}'

Error message

Unable to convert TIMESTAMP_TZ from String value: '${value}' for TiDB dataType: ${dataType}

What it means

convertToOffsetDateTime converts TIMESTAMP_TZ values to OffsetDateTime; when the value is a String it attempts strict ISO-8601 OffsetDateTime.parse. A parse failure raises an IllegalArgumentException including the raw string and the TiDB data type.

Source

Thrown at seatunnel-connectors-v2/connector-cdc/connector-cdc-tidb/src/main/java/org/apache/seatunnel/connectors/seatunnel/cdc/tidb/source/converter/DefaultDataConverter.java:289

        if (value instanceof Timestamp) {
            // TiDB TIMESTAMP is stored in UTC; convert to OffsetDateTime with UTC zone.
            Instant instant = ((Timestamp) value).toInstant();
            return OffsetDateTime.ofInstant(instant, ZoneOffset.UTC);
        }
        if (value instanceof Long) {
            // TiDB may emit TIMESTAMP as epoch milliseconds in some snapshot modes.
            return OffsetDateTime.ofInstant(Instant.ofEpochMilli((Long) value), ZoneOffset.UTC);
        }
        if (value instanceof LocalDateTime) {
            // LocalDateTime without explicit zone — treat as UTC wall-clock value.
            return ((LocalDateTime) value).atOffset(ZoneOffset.UTC);
        }
        if (value instanceof String) {
            // String representation from TiDB CDC — attempt ISO-8601 parse.
            try {
                return OffsetDateTime.parse((String) value);
            } catch (java.time.format.DateTimeParseException e) {
                throw new IllegalArgumentException(
                        "Unable to convert TIMESTAMP_TZ from String value: '"
                                + value
                                + "' for TiDB dataType: "
                                + dataType,
                        e);
            }
        }
        // Unknown type — fail fast with enough context for diagnosis instead of silently
        // returning the raw value which would cause a ClassCastException downstream.
        throw new IllegalArgumentException(
                "Unsupported value type for TIMESTAMP_TZ conversion: "
                        + value.getClass().getName()
                        + ", value='"
                        + value
                        + "', TiDB dataType="
                        + dataType);
    }

View on GitHub (pinned to cf67b549a7)

Solutions

1. Use a formatter matching TiDB's 'yyyy-MM-dd HH:mm:ss[.SSSSSS]' and attach the configured zone instead of OffsetDateTime.parse
2. Set an explicit timezone in the connector/job config so strings are parsed with the intended offset
3. Normalize the value (replace space with 'T', append offset) before parsing
4. Catch DateTimeParseException upstream and fall back to a lenient parser

Example fix

// before
return OffsetDateTime.parse((String) value);
// after
LocalDateTime ldt = LocalDateTime.parse(((String) value).replace(' ', 'T'));
return ldt.atZone(ZoneId.of(timezone)).toOffsetDateTime();

static boolean isIsoOffsetDateTime(String s) {
    try { OffsetDateTime.parse(s); return true; } catch (DateTimeParseException e) { return false; }
}
// normalize first: s = s.replace(' ', 'T'); append zone offset if absent

static boolean looksLikeTimestamp(String s) {
    return s != null && s.matches("\\d{4}-\\d{2}-\\d{2}[ T]\\d{2}:\\d{2}:\\d{2}(.\\d+)?(Z|[+-]\\d{2}:?\\d{2})?");
}

try {
    return convertToOffsetDateTime(value, dataType);
} catch (IllegalArgumentException e) {
    log.error("TIMESTAMP_TZ parse failure for value '{}': {}", value, e.getMessage());
    throw e;
}

When it happens

Trigger: A TIMESTAMP/TIMESTAMPTZ column whose value reaches the converter as a String that is not valid ISO-8601 with offset — e.g. '2024-01-01 10:00:00' (space, no zone) or missing offset.

Common situations: TiDB DATETIME/TIMESTAMP emitted as 'yyyy-MM-dd HH:mm:ss' without timezone; fractional seconds beyond ISO parsing tolerance; server timezone configured differently than expected.

Related errors

• Unsupported value type for TIMESTAMP_TZ conversion: ${value.
• Unable to convert to LocalDateTime from unexpected value '${
• Unable to parse OffsetDateTime from CDC TIMESTAMP_TZ value:
• not supported create new Offset by timestamp.
• Convert timestamp to LSN offset error

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