apache/flink · error · IllegalStateException

Missing value for the key '{}'

Error message

Missing value for the key '{}'

What it means

The counterpart of the missing-key check in LinkedOptionalMap.unwrapOptionals(): an entry has a key but its value is null (KeyValue.value == null), so the map cannot produce a fully-populated LinkedHashMap and throws IllegalStateException naming the entry.

Source

Thrown at flink-core/src/main/java/org/apache/flink/util/LinkedOptionalMap.java:188

    /**
     * Assuming all the entries of this map are present (keys and values) this method would return a
     * map with these key and values, stripped from their Optional wrappers. NOTE: please note that
     * if any of the key or values are absent this method would throw an {@link
     * IllegalStateException}.
     */
    public LinkedHashMap<K, V> unwrapOptionals() {
        final LinkedHashMap<K, V> unwrapped =
                CollectionUtil.newLinkedHashMapWithExpectedSize(underlyingMap.size());

        for (Entry<String, KeyValue<K, V>> entry : underlyingMap.entrySet()) {
            String namedKey = entry.getKey();
            KeyValue<K, V> kv = entry.getValue();
            if (kv.key == null) {
                throw new IllegalStateException("Missing key '" + namedKey + "'");
            }
            if (kv.value == null) {
                throw new IllegalStateException("Missing value for the key '" + namedKey + "'");
            }
            unwrapped.put(kv.key, kv.value);
        }
        return unwrapped;
    }

    /** Returns the key names added to this map. */
    public Set<String> keyNames() {
        return underlyingMap.keySet();
    }

    // --------------------------------------------------------------------------------------------------------
    // Static Utility Methods
    // --------------------------------------------------------------------------------------------------------

    private static <K, V> boolean keyOrValueIsAbsent(Entry<String, KeyValue<K, V>> entry) {
        KeyValue<K, V> kv = entry.getValue();
        return kv.key == null || kv.value == null;

View on GitHub (pinned to 2f3c205e92)

Solutions

1. Locate the entry named in the message and ensure its value is set before unwrapOptionals() runs.
2. Complete or remove half-populated entries prior to unwrapping (iterate keyNames() and check each value).
3. If a value cannot be resolved (factory unavailable), fail early with a clearer error at registration time instead of leaving a null value.
4. Write a validation step asserting all entries have both key and value before the unwrap call.

Example fix

// before
map.put("module-a", moduleKey, null); // value never resolved
map.unwrapOptionals(); // IllegalStateException: Missing value for the key 'module-a'

// after
Module module = moduleFactory.create();
if (module != null) {
    map.put("module-a", moduleKey, module);
}
map.unwrapOptionals();

for (String name : map.keyNames()) {
    if (map.getOption(name) == null /* value absent */) {
        throw new IllegalStateException("Entry '" + name + "' has no value; resolve it before unwrap");
    }
}
LinkedHashMap<K, V> m = map.unwrapOptionals();

When it happens

Trigger: Calling unwrapOptionals() after adding an entry whose key object exists but whose value was never supplied (optional value left absent), e.g. registering a component by name+key without a concrete instance.

Common situations: Optional component registration (table modules, formats, catalogs) where a factory failed or was skipped but the entry stayed in the map; partially-built configuration flows that add names first and values later, with unwrap called before population completes.

Related errors

• Missing key '{}'
• No cluster id was specified. Please specify a cluster to whi
• The configuration directory '{}', specified in the '{}' envi
• The configuration directory was not specified. Please specif
• No valid command-line found.

AI-assisted analysis of apache/flink@2f3c205e92 (2026-08-14). Data as JSON: /api/errors/925ccbdee5214258. Report an issue: GitHub.