{"record":{"id":"06164596b0f70a05","repo":"apache/flink","slug":"json-format-doesn-t-support-to-serialize-map-data","errorCode":null,"errorMessage":"JSON format doesn't support to serialize map data with null keys. You can drop null key entries or encode null in literals by specifying %s option.","messagePattern":"JSON format doesn't support to serialize map data with null keys\\. You can drop null key entries or encode null in literals by specifying (.+?) option\\.","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"flink-formats/flink-json/src/main/java/org/apache/flink/formats/json/RowDataToJsonConverters.java","lineNumber":306,"sourceCode":"                node.removeAll();\n            }\n\n            MapData map = (MapData) object;\n            ArrayData keyArray = map.keyArray();\n            ArrayData valueArray = map.valueArray();\n            int numElements = map.size();\n            for (int i = 0; i < numElements; i++) {\n                String fieldName = null;\n                if (keyArray.isNullAt(i)) {\n                    // when map key is null\n                    switch (mapNullKeyMode) {\n                        case LITERAL:\n                            fieldName = mapNullKeyLiteral;\n                            break;\n                        case DROP:\n                            continue;\n                        case FAIL:\n                            throw new RuntimeException(\n                                    String.format(\n                                            \"JSON format doesn't support to serialize map data with null keys. \"\n                                                    + \"You can drop null key entries or encode null in literals by specifying %s option.\",\n                                            JsonFormatOptions.MAP_NULL_KEY_MODE.key()));\n                        default:\n                            throw new RuntimeException(\n                                    \"Unsupported map null key mode. Validator should have checked that.\");\n                    }\n                } else {\n                    fieldName = keyArray.getString(i).toString();\n                }\n\n                Object value = valueGetter.getElementOrNull(valueArray, i);\n                node.set(fieldName, valueConverter.convert(mapper, node.get(fieldName), value));\n            }\n\n            return node;\n        };","sourceCodeStart":288,"sourceCodeEnd":324,"githubUrl":"https://github.com/apache/flink/blob/2f3c205e9266cb30240eb7f4fdab15cad629a70f/flink-formats/flink-json/src/main/java/org/apache/flink/formats/json/RowDataToJsonConverters.java#L288-L324","documentation":"Thrown by RowDataToJsonConverters.createMapConverter when a map being serialized to JSON has a null key and mapNullKeyMode is FAIL (the default). JSON object keys cannot be null, so the format offers three modes via the 'json.map-null-key.mode' option: FAIL (default), DROP (skip entry), LITERAL (write the string from 'json.map-null-key.literal').","triggerScenarios":"Writing a row whose MAP contains a null key with default options. Commonly from aggregations that produce null keys (e.g. GROUP BY on a nullable column, LEFT JOIN results) feeding a JSON sink such as Kafka with 'format'='json'.","commonSituations":"Null keys from outer joins or optional grouping attributes; upstream data quality issues producing null map keys; switching a sink from a format that tolerated null keys to JSON.","solutions":["Set 'json.map-null-key.mode' = 'DROP' to skip null-key entries","Set 'json.map-null-key.mode' = 'LITERAL' together with 'json.map-null-key.literal' = 'null' (or another marker) to encode null keys as a string","Filter null keys out in the query (WHERE k IS NOT NULL) or COALESCE the key column before it reaches the map"],"exampleFix":"// before\nWITH ('connector'='kafka', 'format'='json')\n-- map {null: 'x'} throws\n\n// after\nWITH ('connector'='kafka', 'format'='json',\n  'json.map-null-key.mode'='LITERAL', 'json.map-null-key.literal'='null')","handlingStrategy":"validation","validationCode":"// Decide policy up front in the WITH clause instead of the FAIL default:\n// 'json.map-null-key.mode' = 'DROP' | 'LITERAL' + 'json.map-null-key.literal'","typeGuard":null,"tryCatchPattern":"catch (RuntimeException e) on null-map-key message — switch map-null-key mode option; the failing record itself is usually legitimate data.","preventionTips":["Always set 'json.map-null-key.mode' explicitly for sink tables fed by joins/aggregations","COALESCE nullable keys before they become map keys","Test sinks with null-key sample rows"],"tags":["json","map","null-key","option","serialization"],"backgroundTag":null,"analyzedSha":"2f3c205e9266cb30240eb7f4fdab15cad629a70f","analyzedAt":"2026-08-14T08:48:24.518Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}