hibernate/hibernate-orm · error · IllegalArgumentException

Provided Connection cannot be null

Error message

Provided Connection cannot be null

What it means

IllegalArgumentException from the LogicalConnectionProvidedImpl constructor: a session variant that requires a user-supplied JDBC Connection was constructed with null. Hibernate itself does not pass null here in normal flows — some caller invoked openSession(connection, ...) or SharedSessionBuilder.connection(...) with a null reference.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/resource/jdbc/internal/LogicalConnectionProvidedImpl.java:36

import static org.hibernate.resource.jdbc.spi.PhysicalConnectionHandlingMode.IMMEDIATE_ACQUISITION_AND_HOLD;

/**
 * @author Steve Ebersole
 */
public class LogicalConnectionProvidedImpl extends AbstractLogicalConnectionImplementor {

	@Nonnull
	protected ResourceRegistry resourceRegistry;
	@Nullable
	private transient Connection providedConnection;
	private final boolean initiallyAutoCommit;
	private boolean closed;

	public LogicalConnectionProvidedImpl(@Nonnull Connection providedConnection, @Nonnull ResourceRegistry resourceRegistry) {
		this.resourceRegistry = resourceRegistry;
		if ( providedConnection == null ) {
			throw new IllegalArgumentException( "Provided Connection cannot be null" );
		}
		this.providedConnection = providedConnection;
		this.initiallyAutoCommit = determineInitialAutoCommitMode( providedConnection );
	}

	private LogicalConnectionProvidedImpl(boolean closed, boolean initiallyAutoCommit) {
		this.resourceRegistry = new ResourceRegistryStandardImpl();
		this.closed = closed;
		this.initiallyAutoCommit = initiallyAutoCommit;
	}

	@Override
	@Nonnull
	public PhysicalConnectionHandlingMode getConnectionHandlingMode() {
		return IMMEDIATE_ACQUISITION_AND_HOLD;
	}

	@Override

View on GitHub (pinned to fad1729dce)

Solutions

1. Null-check the connection before opening the session and fail with a clear message at the call site
2. Fix the producer that returned null (DataSource, connection factory, mock)
3. If you do not actually need a user-supplied connection, use sessionFactory.openSession() and let the pool provide one

Example fix

// before
Session s = sessionFactory.openSession(getConnection()); // getConnection() may return null

// after
Connection c = Objects.requireNonNull(getConnection(), "dataSource.getConnection() returned null");
Session s = sessionFactory.openSession(c);

Connection c = Objects.requireNonNull(getConnection(), "connection source returned null");
Session s = sessionFactory.openSession(c);

catch (IllegalArgumentException e) {
  // constructor guard: a null connection reached openSession — fix the producer,
  // do not retry with the same null source
}

When it happens

Trigger: sessionFactory.openSession((Connection) null); SharedSessionBuilder.connection(null); or openSession(dataSource.getConnection()) where the producer (real or mocked) returned null instead of a connection.

Common situations: Test doubles/mocks whose getConnection() returns null; Optional/nullable plumbing bugs; overload-resolution surprises where the Connection overload is selected with a null argument after a refactor.

Related errors

• cannot reconnect using a null connection
• CacheMode cannot be null
• Passed table name cannot be null
• Informix only supports the case insensitive flag 'i' as lite
• The specified package name cannot be null

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