What causes "Bean instance cannot be null" in hibernate/hibernate-orm?

Never return null from a producer: throw a descriptive exception naming the missing bean type instead.

hibernate/hibernate-orm · error · IllegalArgumentException

Bean instance cannot be null

Error message

Bean instance cannot be null

What it means

ProvidedInstanceManagedBeanImpl is the ManagedBean wrapper Hibernate uses when an actual bean instance is handed to it directly. Every ManagedBean must be able to produce an instance, so the constructor rejects null with IllegalArgumentException('Bean instance cannot be null') - the caller supplied no instance where one is mandatory.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/resource/beans/spi/ProvidedInstanceManagedBeanImpl.java:20

 * SPDX-License-Identifier: Apache-2.0
 * Copyright Red Hat Inc. and Hibernate Authors
 */
package org.hibernate.resource.beans.spi;

import org.hibernate.internal.util.ReflectHelper;

/**
 * {@link ManagedBean} implementation for cases where we have been handed an actual
 * instance to use.
 *
 * @author Steve Ebersole
 */
public class ProvidedInstanceManagedBeanImpl<T> implements ManagedBean<T> {
	private final T instance;

	public ProvidedInstanceManagedBeanImpl(T instance) {
		if ( instance == null ) {
			throw new IllegalArgumentException( "Bean instance cannot be null" );
		}
		this.instance = instance;
	}

	@Override
	public Class<T> getBeanClass() {
		return ReflectHelper.getClass( instance );
	}

	@Override
	public T getBeanInstance() {
		return instance;
	}
}

View on GitHub (pinned to fad1729dce)

Solutions

Never return null from a producer: throw a descriptive exception naming the missing bean type instead.
Null-check at the boundary that hands instances to Hibernate and fail fast with context.
Initialize/verify the instance field before building the SessionFactory.

Example fix

// before
public <B> B produceBeanInstance(Class<B> type) {
    return registry.get(type); // returns null when absent -> IllegalArgumentException
}

// after
public <B> B produceBeanInstance(Class<B> type) {
    B bean = registry.get(type);
    if (bean == null) throw new IllegalStateException("No bean registered for " + type.getName());
    return bean;
}

Defensive patterns

Strategy: validation

Validate before calling

// producers must never hand null to Hibernate
public <B> ManagedBean<B> bean(Class<B> type) {
    B instance = lookup(type);
    java.util.Objects.requireNonNull(instance, () -> "No instance for " + type.getName());
    return new ProvidedInstanceManagedBeanImpl<>(instance);
}

Try / catch

try {
    return new ProvidedInstanceManagedBeanImpl<>(producer.produceBeanInstance(type));
} catch (IllegalArgumentException e) {
    // 'Bean instance cannot be null': producer returned null; fail with bean context
    throw new BeanLookupException("Producer returned null for " + type.getName(), e);
}

Prevention

Throw descriptive exceptions from lookups instead of returning null.
RequireNonNull at every producer boundary.
Initialize the instance registry before SessionFactory construction.

When it happens

Trigger: A custom BeanContainer or BeanInstanceProducer returns null instead of throwing when a bean cannot be looked up, and that null is wrapped into a ManagedBean; or configuration code passes a null bean instance into the managed-bean registry.

Common situations: Hand-written producers whose lookup silently returns null for missing beans; race conditions where a lookup happens before registration and yields null; copy-pasted configuration referencing an unset field.

Related errors

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