{"record":{"id":"d357e1adf846712c","repo":"hibernate/hibernate-orm","slug":"provided-connection-cannot-be-null","errorCode":null,"errorMessage":"Provided Connection cannot be null","messagePattern":"Provided Connection cannot be null","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/resource/jdbc/internal/LogicalConnectionProvidedImpl.java","lineNumber":36,"sourceCode":"\nimport static org.hibernate.resource.jdbc.spi.PhysicalConnectionHandlingMode.IMMEDIATE_ACQUISITION_AND_HOLD;\n\n/**\n * @author Steve Ebersole\n */\npublic class LogicalConnectionProvidedImpl extends AbstractLogicalConnectionImplementor {\n\n\t@Nonnull\n\tprotected ResourceRegistry resourceRegistry;\n\t@Nullable\n\tprivate transient Connection providedConnection;\n\tprivate final boolean initiallyAutoCommit;\n\tprivate boolean closed;\n\n\tpublic LogicalConnectionProvidedImpl(@Nonnull Connection providedConnection, @Nonnull ResourceRegistry resourceRegistry) {\n\t\tthis.resourceRegistry = resourceRegistry;\n\t\tif ( providedConnection == null ) {\n\t\t\tthrow new IllegalArgumentException( \"Provided Connection cannot be null\" );\n\t\t}\n\t\tthis.providedConnection = providedConnection;\n\t\tthis.initiallyAutoCommit = determineInitialAutoCommitMode( providedConnection );\n\t}\n\n\tprivate LogicalConnectionProvidedImpl(boolean closed, boolean initiallyAutoCommit) {\n\t\tthis.resourceRegistry = new ResourceRegistryStandardImpl();\n\t\tthis.closed = closed;\n\t\tthis.initiallyAutoCommit = initiallyAutoCommit;\n\t}\n\n\t@Override\n\t@Nonnull\n\tpublic PhysicalConnectionHandlingMode getConnectionHandlingMode() {\n\t\treturn IMMEDIATE_ACQUISITION_AND_HOLD;\n\t}\n\n\t@Override","sourceCodeStart":18,"sourceCodeEnd":54,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/resource/jdbc/internal/LogicalConnectionProvidedImpl.java#L18-L54","documentation":"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.","triggerScenarios":"sessionFactory.openSession((Connection) null); SharedSessionBuilder.connection(null); or openSession(dataSource.getConnection()) where the producer (real or mocked) returned null instead of a connection.","commonSituations":"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.","solutions":["Null-check the connection before opening the session and fail with a clear message at the call site","Fix the producer that returned null (DataSource, connection factory, mock)","If you do not actually need a user-supplied connection, use sessionFactory.openSession() and let the pool provide one"],"exampleFix":"// before\nSession s = sessionFactory.openSession(getConnection()); // getConnection() may return null\n\n// after\nConnection c = Objects.requireNonNull(getConnection(), \"dataSource.getConnection() returned null\");\nSession s = sessionFactory.openSession(c);","handlingStrategy":"validation","validationCode":"Connection c = Objects.requireNonNull(getConnection(), \"connection source returned null\");\nSession s = sessionFactory.openSession(c);","typeGuard":null,"tryCatchPattern":"catch (IllegalArgumentException e) {\n  // constructor guard: a null connection reached openSession — fix the producer,\n  // do not retry with the same null source\n}","preventionTips":["Null-check every externally produced Connection before handing it to Hibernate","Make mocks/stubs of DataSource.getConnection() return real or proxy connections, never null","Prefer pooled sessions (openSession()) unless a user-supplied connection is required"],"tags":["hibernate","session","null-check","illegal-argument"],"backgroundTag":"illegal-null-argument","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}