What causes "This map does not support null keys" in hibernate/hibernate-orm?

Null-check the key before put and skip or log the null case deliberately

hibernate/hibernate-orm · error · NullPointerException

This map does not support null keys

Error message

This map does not support null keys

What it means

InstanceIdentityMap.put(K key, V value) rejects a null key immediately with NullPointerException and the message 'This map does not support null keys'. Entries are addressed by key.$$_hibernate_getInstanceId(), so a null key has no addressable identity — the map fails fast rather than masking the problem in a HashMap-like null bucket.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/internal/util/collections/InstanceIdentityMap.java:148

	}

	/**
	 * {@inheritDoc}
	 * @implNote This only works for {@link InstanceIdentity} keys, and it's inefficient
	 * since we need to do a type check. Prefer using {@link #get(int, Object)}.
	 */
	@Override
	public @Nullable V get(Object key) {
		if ( key instanceof InstanceIdentity instance ) {
			return get( instance.$$_hibernate_getInstanceId(), instance );
		}
		throw new ClassCastException( "Provided key does not support instance identity" );
	}

	@Override
	public @Nullable V put(K key, V value) {
		if ( key == null ) {
			throw new NullPointerException( "This map does not support null keys" );
		}

		final int index = key.$$_hibernate_getInstanceId() - 1;
		if ( index < 0 ) {
			throw new IllegalArgumentException( "Instance ID must be a positive value" );
		}

		final Map.Entry<K, V> old = set( index, new AbstractMap.SimpleImmutableEntry<>( key, value ) );
		if ( old == null ) {
			size++;
			return null;
		}
		else {
			return old.getValue();
		}
	}

	/**

View on GitHub (pinned to fad1729dce)

Solutions

Null-check the key before put and skip or log the null case deliberately
Trace where the null entity came from — usually a session.get()/find() that returned null for a missing row
Never substitute null keys; if absence is meaningful, store a sentinel object or use a separate set

Example fix

// before
map.put( entity, state );
// after
if ( entity == null ) {
    throw new IllegalArgumentException( "entity must be loaded before insertion" );
}
map.put( entity, state );

Defensive patterns

Strategy: validation

Validate before calling

if ( key == null ) {
    // deliberate policy: skip, or fail with context
    throw new IllegalArgumentException( "key must be a loaded entity, got null" );
}
map.put( key, value );

Prevention

Null-check entity references right after session.get()/find() and before any map insertion
Never use null as a stand-in key; model absence explicitly
Enable -XX:+ShowMessageBoxOnError style strictness in tests via Objects.requireNonNull(key) at API boundaries

When it happens

Trigger: put(null, value) — typically a key variable that was null-checked nowhere upstream: an entity reference that failed to load, a lookup that returned null, or a defensive default of null.

Common situations: Putting entities into instance-identity storage without checking whether the preceding load/find actually returned an object; Optional-unwrapping defaults of null; copy loops from another map that legitimately contained null keys.

Related errors

AI-assisted analysis of hibernate/hibernate-orm@fad1729dce (2026-08-22). Data as JSON: /api/errors/826be4102e66d3e5. Report an issue: GitHub.