{"record":{"id":"da43d68ca26f0f17","repo":"apache/flink","slug":"unsupported-timestamp-format-s-validator-shoul","errorCode":null,"errorMessage":"Unsupported timestamp format '%s'. Validator should have checked that.","messagePattern":"Unsupported timestamp format '(.+?)'\\. Validator should have checked that\\.","errorType":"exception","errorClass":"TableException","httpStatus":null,"severity":"error","filePath":"flink-formats/flink-json/src/main/java/org/apache/flink/formats/json/JsonFormatOptionsUtil.java","lineNumber":69,"sourceCode":"\n    // The handling mode of null key for map data\n    public static final String JSON_MAP_NULL_KEY_MODE_FAIL = \"FAIL\";\n    public static final String JSON_MAP_NULL_KEY_MODE_DROP = \"DROP\";\n    public static final String JSON_MAP_NULL_KEY_MODE_LITERAL = \"LITERAL\";\n\n    // --------------------------------------------------------------------------------------------\n    // Utilities\n    // --------------------------------------------------------------------------------------------\n\n    public static TimestampFormat getTimestampFormat(ReadableConfig config) {\n        String timestampFormat = config.get(TIMESTAMP_FORMAT);\n        switch (timestampFormat) {\n            case SQL:\n                return TimestampFormat.SQL;\n            case ISO_8601:\n                return TimestampFormat.ISO_8601;\n            default:\n                throw new TableException(\n                        String.format(\n                                \"Unsupported timestamp format '%s'. Validator should have checked that.\",\n                                timestampFormat));\n        }\n    }\n\n    /**\n     * Creates handling mode for null key map data.\n     *\n     * <p>See {@link #JSON_MAP_NULL_KEY_MODE_FAIL}, {@link #JSON_MAP_NULL_KEY_MODE_DROP}, and {@link\n     * #JSON_MAP_NULL_KEY_MODE_LITERAL} for more information.\n     */\n    public static JsonFormatOptions.MapNullKeyMode getMapNullKeyMode(ReadableConfig config) {\n        String mapNullKeyMode = config.get(MAP_NULL_KEY_MODE);\n        switch (mapNullKeyMode.toUpperCase()) {\n            case JSON_MAP_NULL_KEY_MODE_FAIL:\n                return JsonFormatOptions.MapNullKeyMode.FAIL;\n            case JSON_MAP_NULL_KEY_MODE_DROP:","sourceCodeStart":51,"sourceCodeEnd":87,"githubUrl":"https://github.com/apache/flink/blob/2f3c205e9266cb30240eb7f4fdab15cad629a70f/flink-formats/flink-json/src/main/java/org/apache/flink/formats/json/JsonFormatOptionsUtil.java#L51-L87","documentation":"TableException from JsonFormatOptionsUtil.getTimestampFormat when the 'timestamp-format' option string is neither 'SQL' nor 'ISO-8601'. The message states the validator should have caught this: it only triggers when the config was assembled programmatically (or mutated) without running validateDecodingFormatOptions/validateEncodingFormatOptions first.","triggerScenarios":"Building a ReadableConfig by hand and calling getTimestampFormat directly; a custom format factory skipping validation; case-sensitivity mismatch ('sql' lowercase, since the switch is exact-match on SQL/ISO_8601 constants).","commonSituations":"Custom DynamicTableFactory reusing JsonFormatOptionsUtil without the validate step; option set via Configuration.set with an unchecked string; downstream code bypassing DDL validation.","solutions":["Use exactly 'SQL' or 'ISO-8601' (case-sensitive) for 'timestamp-format'","Call JsonFormatOptionsUtil.validateDecodingFormatOptions/validateEncodingFormatOptions before getTimestampFormat in custom factories","Prefer defining the table via DDL so the standard validator runs"],"exampleFix":"-- before\n'timestamp-format' = 'sql'\n\n-- after\n'timestamp-format' = 'SQL'","handlingStrategy":"validation","validationCode":"Set<String> ok = new HashSet<>(Arrays.asList(\"SQL\", \"ISO-8601\"));\nif (!ok.contains(config.get(JsonFormatOptions.TIMESTAMP_FORMAT))) {\n    throw new ValidationException(\"timestamp-format must be SQL or ISO-8601\");\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Pin option values to the documented exact-case spellings","Run the format validators in any custom factory before reading options"],"tags":["flink","json","options","timestamp","validation"],"backgroundTag":null,"analyzedSha":"2f3c205e9266cb30240eb7f4fdab15cad629a70f","analyzedAt":"2026-08-14T08:48:24.518Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}