{"record":{"id":"69a86bc71790f492","repo":"apache/flink","slug":"unsupported-map-null-key-handling-mode-s-valid","errorCode":null,"errorMessage":"Unsupported map null key handling mode '%s'. Validator should have checked that.","messagePattern":"Unsupported map null key handling mode '(.+?)'\\. 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":92,"sourceCode":"    }\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:\n                return JsonFormatOptions.MapNullKeyMode.DROP;\n            case JSON_MAP_NULL_KEY_MODE_LITERAL:\n                return JsonFormatOptions.MapNullKeyMode.LITERAL;\n            default:\n                throw new TableException(\n                        String.format(\n                                \"Unsupported map null key handling mode '%s'. Validator should have checked that.\",\n                                mapNullKeyMode));\n        }\n    }\n\n    // --------------------------------------------------------------------------------------------\n    // Validation\n    // --------------------------------------------------------------------------------------------\n\n    /** Validator for json decoding format. */\n    public static void validateDecodingFormatOptions(ReadableConfig tableOptions) {\n        boolean failOnMissingField = tableOptions.get(FAIL_ON_MISSING_FIELD);\n        boolean ignoreParseErrors = tableOptions.get(IGNORE_PARSE_ERRORS);\n        if (ignoreParseErrors && failOnMissingField) {\n            throw new ValidationException(\n                    FAIL_ON_MISSING_FIELD.key()\n                            + \" and \"","sourceCodeStart":74,"sourceCodeEnd":110,"githubUrl":"https://github.com/apache/flink/blob/2f3c205e9266cb30240eb7f4fdab15cad629a70f/flink-formats/flink-json/src/main/java/org/apache/flink/formats/json/JsonFormatOptionsUtil.java#L74-L110","documentation":"TableException from JsonFormatOptionsUtil.getMapNullKeyMode when 'map-null-key.mode' is not fail/drop/literal (compared upper-case after toUpperCase()). It is the same 'validator should have caught it' pattern: the runtime switch only sees an unknown mode when validation was skipped or the enum set drifted between versions.","triggerScenarios":"Programmatic ReadableConfig usage without validateEncodingFormatOptions; a value like 'FAILS' or 'raise' that upper-cases to none of FAIL/DROP/LITERAL.","commonSituations":"Custom factories bypassing validation; typos in programmatically-set options; docs/versions mismatch where an old mode name was removed.","solutions":["Set 'map-null-key.mode' to one of 'FAIL', 'DROP', or 'LITERAL' (any case; it is upper-cased)","Run validateEncodingFormatOptions(tableOptions) before getMapNullKeyMode in custom code","Define the table through DDL so validation happens automatically"],"exampleFix":"-- before\n'map-null-key.mode' = 'skip'\n\n-- after\n'map-null-key.mode' = 'DROP'","handlingStrategy":"validation","validationCode":"Set<String> modes = Arrays.stream(MapNullKeyMode.values()).map(Enum::name).collect(Collectors.toSet());\nif (!modes.contains(config.get(MAP_NULL_KEY_MODE).toUpperCase())) {\n    throw new ValidationException(\"map-null-key.mode must be FAIL, DROP or LITERAL\");\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Use the enum name as the option value source in templates","Validate in custom factories; DDL path already validates"],"tags":["flink","json","options","map","validation"],"backgroundTag":null,"analyzedSha":"2f3c205e9266cb30240eb7f4fdab15cad629a70f","analyzedAt":"2026-08-14T08:48:24.518Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}