{"record":{"id":"96f543a03e8a6505","repo":"apache/flink","slug":"missing-key","errorCode":null,"errorMessage":"Missing key '{}'","messagePattern":"Missing key '(.+?)'","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"flink-core/src/main/java/org/apache/flink/util/LinkedOptionalMap.java","lineNumber":185,"sourceCode":"                .map(Entry::getValue)\n                .collect(Collectors.toCollection(LinkedHashSet::new));\n    }\n\n    /**\n     * Assuming all the entries of this map are present (keys and values) this method would return a\n     * map with these key and values, stripped from their Optional wrappers. NOTE: please note that\n     * if any of the key or values are absent this method would throw an {@link\n     * IllegalStateException}.\n     */\n    public LinkedHashMap<K, V> unwrapOptionals() {\n        final LinkedHashMap<K, V> unwrapped =\n                CollectionUtil.newLinkedHashMapWithExpectedSize(underlyingMap.size());\n\n        for (Entry<String, KeyValue<K, V>> entry : underlyingMap.entrySet()) {\n            String namedKey = entry.getKey();\n            KeyValue<K, V> kv = entry.getValue();\n            if (kv.key == null) {\n                throw new IllegalStateException(\"Missing key '\" + namedKey + \"'\");\n            }\n            if (kv.value == null) {\n                throw new IllegalStateException(\"Missing value for the key '\" + namedKey + \"'\");\n            }\n            unwrapped.put(kv.key, kv.value);\n        }\n        return unwrapped;\n    }\n\n    /** Returns the key names added to this map. */\n    public Set<String> keyNames() {\n        return underlyingMap.keySet();\n    }\n\n    // --------------------------------------------------------------------------------------------------------\n    // Static Utility Methods\n    // --------------------------------------------------------------------------------------------------------\n","sourceCodeStart":167,"sourceCodeEnd":203,"githubUrl":"https://github.com/apache/flink/blob/2f3c205e9266cb30240eb7f4fdab15cad629a70f/flink-core/src/main/java/org/apache/flink/util/LinkedOptionalMap.java#L167-L203","documentation":"LinkedOptionalMap stores named key/value pairs where either side may be absent (wrapped Optional-like semantics via null KeyValue fields). unwrapOptionals() strips the Optional layer into a plain LinkedHashMap, and throws IllegalStateException if an entry's key is null — i.e. the entry was added as an optional/marker entry whose key was never supplied.","triggerScenarios":"Calling unwrapOptionals() after adding entries with a null key — via put/putOptional-style methods where only a value or only a name was recorded (KeyValue.key == null) — such as in Table/SQL module or catalog wiring that uses LinkedOptionalMap for optional dependencies.","commonSituations":"Building a pipeline of optional components (e.g. table module loading, function catalog setup) where a component was registered by name but its key object was left absent, then a downstream consumer demands fully-populated entries by calling unwrapOptionals().","solutions":["Find which entry name (printed in the message) has a missing key and ensure both key and value are set when adding it.","Before unwrapping, call keyNames() / inspect entries and drop or complete entries with absent keys instead of unwrapping blindly.","If the entry is genuinely optional, skip adding it at all rather than adding it half-populated.","Add a unit test that asserts every registered entry is complete before unwrapOptionals is reached."],"exampleFix":"// before\nmap.putOptional(\"module-a\", /* key absent */ null, moduleValue);\nmap.unwrapOptionals(); // IllegalStateException: Missing key 'module-a'\n\n// after\nif (moduleKey != null) {\n    map.put(\"module-a\", moduleKey, moduleValue);\n}\nmap.unwrapOptionals();","handlingStrategy":"validation","validationCode":"for (String name : map.keyNames()) {\n    if (!map.containsKey(name)) { // or equivalent accessor showing key is absent\n        throw new IllegalStateException(\"Entry '\" + name + \"' has no key; complete or remove it\");\n    }\n}\nLinkedHashMap<K, V> m = map.unwrapOptionals();","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Only add fully-populated entries (key and value) to LinkedOptionalMap","Skip optional entries entirely rather than adding them half-empty","Assert map completeness in tests before unwrapOptionals is called"],"tags":["map","optional","configuration","table"],"backgroundTag":null,"analyzedSha":"2f3c205e9266cb30240eb7f4fdab15cad629a70f","analyzedAt":"2026-08-14T08:48:24.518Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}