{"record":{"id":"97162a985b8cba01","repo":"hibernate/hibernate-orm","slug":"only-connectionreleasemode-on-close-can-be-used-in","errorCode":null,"errorMessage":"Only ConnectionReleaseMode.ON_CLOSE can be used in combination with ConnectionAcquisitionMode.IMMEDIATELY; but ConnectionReleaseMode.{} was specified.","messagePattern":"Only ConnectionReleaseMode\\.ON_CLOSE can be used in combination with ConnectionAcquisitionMode\\.IMMEDIATELY; but ConnectionReleaseMode\\.(.+?) was specified\\.","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/resource/jdbc/spi/PhysicalConnectionHandlingMode.java","lineNumber":104,"sourceCode":"\t\t\treturn null;\n\t\t}\n\t}\n\n\tpublic static PhysicalConnectionHandlingMode interpret(\n\t\t\tConnectionAcquisitionMode acquisitionMode,\n\t\t\tConnectionReleaseMode releaseMode) {\n\t\trequireNonNull( acquisitionMode, \"ConnectionAcquisitionMode must be specified\" );\n\t\trequireNonNull( acquisitionMode, \"ConnectionReleaseMode must be specified\" );\n\t\treturn switch ( acquisitionMode ) {\n\t\t\tcase AS_NEEDED -> switch ( releaseMode ) {\n\t\t\t\tcase ON_CLOSE -> DELAYED_ACQUISITION_AND_HOLD;\n\t\t\t\tcase AFTER_STATEMENT -> DELAYED_ACQUISITION_AND_RELEASE_AFTER_STATEMENT;\n\t\t\t\tcase BEFORE_TRANSACTION_COMPLETION -> DELAYED_ACQUISITION_AND_RELEASE_BEFORE_TRANSACTION_COMPLETION;\n\t\t\t\tcase AFTER_TRANSACTION -> DELAYED_ACQUISITION_AND_RELEASE_AFTER_TRANSACTION;\n\t\t\t};\n\t\t\tcase IMMEDIATELY -> switch ( releaseMode ) {\n\t\t\t\tcase ON_CLOSE -> IMMEDIATE_ACQUISITION_AND_HOLD;\n\t\t\t\tdefault -> throw new IllegalArgumentException(\n\t\t\t\t\t\t\"Only ConnectionReleaseMode.ON_CLOSE can be used in combination with \"\n\t\t\t\t\t\t+ \"ConnectionAcquisitionMode.IMMEDIATELY; but ConnectionReleaseMode.\"\n\t\t\t\t\t\t+ releaseMode.name() + \" was specified.\"\n\t\t\t\t);\n\t\t\t};\n\t\t};\n\t}\n}\n","sourceCodeStart":86,"sourceCodeEnd":113,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/resource/jdbc/spi/PhysicalConnectionHandlingMode.java#L86-L113","documentation":"IllegalArgumentException thrown while interpreting the connection handling mode from its two parts: ConnectionAcquisitionMode.IMMEDIATELY is only legal combined with ConnectionReleaseMode.ON_CLOSE. Eagerly acquiring a connection and then releasing it after each statement/transaction is contradictory, so Hibernate rejects the pairing at bootstrap. (Quirk of this version: the second requireNonNull re-checks acquisitionMode, so a null releaseMode is not caught at this spot.)","triggerScenarios":"Setting hibernate.connection.acquisition_mode=IMMEDIATELY together with a release mode other than ON_CLOSE (hibernate.connection.release_mode=AFTER_TRANSACTION / AFTER_STATEMENT / BEFORE_TRANSACTION_COMPLETION), or calling PhysicalConnectionHandlingMode.interpret(IMMEDIATELY, <non-ON_CLOSE>) programmatically while building the SessionFactory.","commonSituations":"Tuning connection handling for bulk loading or schema tools (which require IMMEDIATELY+ON_CLOSE) while an old release_mode property survives in the config; programmatic SessionFactory setup copying incompatible mode combinations; upgrades where config keys moved to the combined handling_mode form.","solutions":["Use one canonical combined value instead: hibernate.connection.handling_mode=IMMEDIATE_ACQUISITION_AND_HOLD","Or keep acquisition IMMEDIATELY and change the release mode to ON_CLOSE","Or switch acquisition to AS_NEEDED if you really want after-statement/after-transaction release","Audit the config for leftover hibernate.connection.release_mode entries when enabling acquisition_mode=IMMEDIATELY"],"exampleFix":"// before\nsettings.put(\"hibernate.connection.acquisition_mode\", \"IMMEDIATELY\");\nsettings.put(\"hibernate.connection.release_mode\", \"AFTER_TRANSACTION\"); // IllegalArgumentException at bootstrap\n\n// after\nsettings.put(\"hibernate.connection.handling_mode\", \"IMMEDIATE_ACQUISITION_AND_HOLD\");","handlingStrategy":"validation","validationCode":"// fail fast with a clear message before bootstrapping\nif (acquisition == org.hibernate.resource.jdbc.spi.ConnectionAcquisitionMode.IMMEDIATELY\n        && release != org.hibernate.ConnectionReleaseMode.ON_CLOSE) {\n  throw new IllegalStateException(\n      \"ConnectionAcquisitionMode.IMMEDIATELY requires ConnectionReleaseMode.ON_CLOSE\");\n}","typeGuard":null,"tryCatchPattern":"catch (IllegalArgumentException e) {\n  // bootstrap rejected the acquisition/release pairing: correct the config to a\n  // canonical handling mode and rebuild — do not catch-and-continue in production\n}","preventionTips":["Prefer the single combined property hibernate.connection.handling_mode with a canonical value","When adding acquisition_mode=IMMEDIATELY, remove any leftover release_mode setting","Validate configuration in a startup smoke test before deployment"],"tags":["hibernate","configuration","bootstrap","connection-management"],"backgroundTag":"invalid-configuration","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}