{"record":{"id":"326b745d35d8f478","repo":"apache/flink","slug":"invalid-time-zone-for-s-the-value-should-be-a","errorCode":null,"errorMessage":"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.","messagePattern":"Invalid time zone for '(.+?)'\\. 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\\.","errorType":"validation","errorClass":"ValidationException","httpStatus":null,"severity":"error","filePath":"flink-connectors/flink-connector-files/src/main/java/org/apache/flink/connector/file/table/FileSystemTableFactory.java","lineNumber":228,"sourceCode":"                        .collect(Collectors.toList());\n\n        return !matchingFactories.isEmpty();\n    }\n\n    /** Similar logic as for {@link TableConfig}. */\n    protected void validateTimeZone(String zone) {\n        boolean isValid;\n        try {\n            // We enforce a zone string that is compatible with both java.util.TimeZone and\n            // java.time.ZoneId to avoid bugs.\n            // In general, advertising either TZDB ID, GMT+xx:xx, or UTC is the best we can do.\n            isValid = java.util.TimeZone.getTimeZone(zone).toZoneId().equals(ZoneId.of(zone));\n        } catch (Exception e) {\n            isValid = false;\n        }\n\n        if (!isValid) {\n            throw new ValidationException(\n                    String.format(\n                            \"Invalid time zone for '%s'. The value should be a Time Zone Database (TZDB) ID \"\n                                    + \"such as 'America/Los_Angeles' to include daylight saving time. Fixed \"\n                                    + \"offsets are supported using 'GMT-03:00' or 'GMT+03:00'. Or use 'UTC' \"\n                                    + \"without time zone and daylight saving time.\",\n                            FileSystemConnectorOptions.SINK_PARTITION_COMMIT_WATERMARK_TIME_ZONE\n                                    .key()));\n        }\n    }\n}\n","sourceCodeStart":210,"sourceCodeEnd":239,"githubUrl":"https://github.com/apache/flink/blob/2f3c205e9266cb30240eb7f4fdab15cad629a70f/flink-connectors/flink-connector-files/src/main/java/org/apache/flink/connector/file/table/FileSystemTableFactory.java#L210-L239","documentation":"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).","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"-- before\n'sink.partition-commit.watermark-timezone' = 'PST'\n\n-- after\n'sink.partition-commit.watermark-timezone' = 'America/Los_Angeles'","handlingStrategy":"validation","validationCode":"// Validate time zone before table creation\nString zone = options.get(\"sink.partition-commit.watermark-timezone\");\nif (zone != null) {\n    try {\n        boolean valid = java.util.TimeZone.getTimeZone(zone).toZoneId()\n            .equals(java.time.ZoneId.of(zone));\n        if (!valid) {\n            throw new ValidationException(\"Invalid time zone: \" + zone);\n        }\n    } catch (Exception e) {\n        throw new ValidationException(\"Invalid time zone: \" + zone, e);\n    }\n}","typeGuard":"boolean isValidTimeZone(String zone) {\n    try {\n        return java.util.TimeZone.getTimeZone(zone).toZoneId()\n            .equals(java.time.ZoneId.of(zone));\n    } catch (Exception e) {\n        return false;\n    }\n}","tryCatchPattern":null,"preventionTips":["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."],"tags":["table-factory","time-zone","validation","partition-commit","flink"],"backgroundTag":null,"analyzedSha":"2f3c205e9266cb30240eb7f4fdab15cad629a70f","analyzedAt":"2026-08-14T08:48:24.518Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}