apache/flink · error · ValidationException

Invalid time zone for '%s'. The value should be a Time Zone

Error message

Invalid time zone for '%s'. The value should be a Time Zone Database (TZDB) ID such as 'America/Los_Angeles' to include daylight saving time. Fixed offsets are supported using 'GMT-03:00' or 'GMT+03:00'. Or use 'UTC' without time zone and daylight saving time.

What it means

FileSystemTableFactory.validateTimeZone validates the SINK_PARTITION_COMMIT_WATERMARK_TIME_ZONE option. It checks that the zone string resolves to the same ZoneId via both java.util.TimeZone.getTimeZone(zone).toZoneId() and java.time.ZoneId.of(zone). If they disagree or ZoneId.of throws, the zone is considered invalid and a ValidationException is thrown. This dual check avoids bugs from TimeZone's fallback behavior (TimeZone.getTimeZone returns GMT for unknown zones rather than failing).

Source

Thrown at flink-connectors/flink-connector-files/src/main/java/org/apache/flink/connector/file/table/FileSystemTableFactory.java:228

                        .collect(Collectors.toList());

        return !matchingFactories.isEmpty();
    }

    /** Similar logic as for {@link TableConfig}. */
    protected void validateTimeZone(String zone) {
        boolean isValid;
        try {
            // We enforce a zone string that is compatible with both java.util.TimeZone and
            // java.time.ZoneId to avoid bugs.
            // In general, advertising either TZDB ID, GMT+xx:xx, or UTC is the best we can do.
            isValid = java.util.TimeZone.getTimeZone(zone).toZoneId().equals(ZoneId.of(zone));
        } catch (Exception e) {
            isValid = false;
        }

        if (!isValid) {
            throw new ValidationException(
                    String.format(
                            "Invalid time zone for '%s'. The value should be a Time Zone Database (TZDB) ID "
                                    + "such as 'America/Los_Angeles' to include daylight saving time. Fixed "
                                    + "offsets are supported using 'GMT-03:00' or 'GMT+03:00'. Or use 'UTC' "
                                    + "without time zone and daylight saving time.",
                            FileSystemConnectorOptions.SINK_PARTITION_COMMIT_WATERMARK_TIME_ZONE
                                    .key()));
        }
    }
}

View on GitHub (pinned to 2f3c205e92)

Solutions

Use a canonical TZDB ID such as 'America/Los_Angeles', 'Europe/Berlin', 'Asia/Shanghai'.
For fixed offsets, use the full format: 'GMT+08:00' or 'GMT-03:00' (with colon and two-digit hours).
Use 'UTC' for no timezone offset.
Avoid ambiguous abbreviations like 'PST', 'EST', 'IST' — use the full IANA ID instead.

Example fix

-- before
'sink.partition-commit.watermark-timezone' = 'PST'

-- after
'sink.partition-commit.watermark-timezone' = 'America/Los_Angeles'

Defensive patterns

Strategy: validation

Validate before calling

// Validate time zone before table creation
String zone = options.get("sink.partition-commit.watermark-timezone");
if (zone != null) {
    try {
        boolean valid = java.util.TimeZone.getTimeZone(zone).toZoneId()
            .equals(java.time.ZoneId.of(zone));
        if (!valid) {
            throw new ValidationException("Invalid time zone: " + zone);
        }
    } catch (Exception e) {
        throw new ValidationException("Invalid time zone: " + zone, e);
    }
}

Type guard

boolean isValidTimeZone(String zone) {
    try {
        return java.util.TimeZone.getTimeZone(zone).toZoneId()
            .equals(java.time.ZoneId.of(zone));
    } catch (Exception e) {
        return false;
    }
}

Prevention

Use canonical IANA TZDB IDs (e.g. 'America/Los_Angeles') instead of abbreviations.
For fixed offsets, use 'GMT+HH:MM' format with colon and two-digit hours.
Use 'UTC' when no timezone behavior is needed.
Test timezone strings in a development environment before deploying to production.

When it happens

Trigger: The table option sink.partition-commit.watermark-timezone is set to a string that is not a valid TZDB ID, GMT offset, or 'UTC'. For example: 'PST' (ambiguous), 'GMT+8' (wrong format, should be 'GMT+08:00'), 'America/New_York' on a JVM where ZoneId.of fails, or any arbitrary string.

Common situations: Setting a shorthand timezone like 'PST' or 'EST' which TimeZone accepts but ZoneId may not round-trip identically. Using 'GMT+8' instead of 'GMT+08:00'. Typo in a timezone ID. Using a non-IANA timezone identifier.

Related errors

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