oracle/graal · error · UnsupportedOperationException

null not supported

Error message

null not supported

What it means

org.graalvm.collections (EconomicMap/EconomicSet) does not permit null keys or elements by design. EconomicMapImpl.checkNonNull is invoked by most map/set operations (put, get, get(default), removeKey, contains, add, remove) and throws UnsupportedOperationException('null not supported') whenever a null key or element is passed. Unlike java.util.HashMap, null is never silently tolerated.

Source

Thrown at sdk/src/org.graalvm.collections/src/org/graalvm/collections/EconomicMapImpl.java:681

        checkNonNull(key);
        int index;
        if (hasHashArray()) {
            index = this.findAndRemoveHash(key);
        } else {
            index = this.findLinear(key);
        }

        if (index != -1) {
            Object value = getValue(index);
            remove(index);
            return (V) value;
        }
        return null;
    }

    static void checkNonNull(Object key) {
        if (key == null) {
            throw new UnsupportedOperationException("null not supported");
        }
    }

    /**
     * Removes the element at the specific index and returns the index of the next element. This can
     * be a different value if graph compression was triggered.
     */
    private int remove(int indexToRemove) {
        int index = indexToRemove;
        int entriesAfterIndex = totalEntries - index - 1;
        int result = index + 1;

        // Without hash array, compress immediately.
        if (entriesAfterIndex <= COMPRESS_IMMEDIATE_CAPACITY && !hasHashArray()) {
            while (index < totalEntries - 1) {
                setKey(index, getKey(index + 1));
                setRawValue(index, getRawValue(index + 1));
                index++;

View on GitHub (pinned to a66e9ccd1d)

Solutions

1. Null-check keys/elements before every EconomicMap/EconomicSet call, or use a sentinel value (e.g. a static EMPTY_KEY object) instead of null.
2. Audit the data source feeding the map: if a null key is legitimate, store it in a java.util.HashMap alongside the EconomicMap, or normalize nulls to a sentinel at insertion time.
3. If wrapping a JDK collection with EconomicMap.wrap/ EconomicSet.wrap, filter or reject null keys/elements in the source collection first.

Example fix

// before
Object cached = map.get(someField.getId()); // getId() may return null

// after
Object id = someField.getId();
Object cached = (id != null) ? map.get(id) : null;

static <K> boolean isUsableKey(K key) {
    return key != null;
}
// EconomicMap.map -> Objects.requireNonNull(key, "EconomicMap forbids null keys");

Catch UnsupportedOperationException at the boundary that accepts external keys, rethrow as IllegalArgumentException with your key's provenance so the null source is identifiable.

When it happens

Trigger: Calling EconomicMap.put(null, v), map.get(null), map.removeKey(null), map.containsKey(null), EconomicSet.add(null), set.contains(null), or any EconomicStorage method routed through EconomicMapImpl.checkNonNull with a null argument. Also hit indirectly when EconomicMap.wrap(java.util.Map) or EconomicSet.wrap(Set) is given a JDK map/set that actually contains a null key/element.

Common situations: Porting code from java.util.HashMap/HashSet (which allow null keys) to EconomicMap/EconomicSet for memory/speed; data-driven lookups where a map lookup key comes from an optional field that was never null-checked; wrapping an external Map that contains nulls (e.g. parsed config or JSON with nulls).

Related errors

• map grown too large!
• endless collision link cycle, most likely due to unsynchroni
• Cannot modify the always-empty map
• Required replay field is null
• no value provided

AI-assisted analysis of oracle/graal@a66e9ccd1d (2026-08-14). Data as JSON: /api/errors/7722032c13859690. Report an issue: GitHub.