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.

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
• A TypeInfoFactory for type
• argument is an empty- or whitespace-only string
• Artifact fetching from raw HTTP endpoints are disabled. Set…
• At least one trigger condition must be configured.

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

Appendix: 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)