hibernate/hibernate-orm · error · IllegalArgumentException

Only ConnectionReleaseMode.ON_CLOSE can be used in combinati

Error message

Only ConnectionReleaseMode.ON_CLOSE can be used in combination with ConnectionAcquisitionMode.IMMEDIATELY; but ConnectionReleaseMode.{} was specified.

What it means

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.)

Source

Thrown at hibernate-core/src/main/java/org/hibernate/resource/jdbc/spi/PhysicalConnectionHandlingMode.java:104

			return null;
		}
	}

	public static PhysicalConnectionHandlingMode interpret(
			ConnectionAcquisitionMode acquisitionMode,
			ConnectionReleaseMode releaseMode) {
		requireNonNull( acquisitionMode, "ConnectionAcquisitionMode must be specified" );
		requireNonNull( acquisitionMode, "ConnectionReleaseMode must be specified" );
		return switch ( acquisitionMode ) {
			case AS_NEEDED -> switch ( releaseMode ) {
				case ON_CLOSE -> DELAYED_ACQUISITION_AND_HOLD;
				case AFTER_STATEMENT -> DELAYED_ACQUISITION_AND_RELEASE_AFTER_STATEMENT;
				case BEFORE_TRANSACTION_COMPLETION -> DELAYED_ACQUISITION_AND_RELEASE_BEFORE_TRANSACTION_COMPLETION;
				case AFTER_TRANSACTION -> DELAYED_ACQUISITION_AND_RELEASE_AFTER_TRANSACTION;
			};
			case IMMEDIATELY -> switch ( releaseMode ) {
				case ON_CLOSE -> IMMEDIATE_ACQUISITION_AND_HOLD;
				default -> throw new IllegalArgumentException(
						"Only ConnectionReleaseMode.ON_CLOSE can be used in combination with "
						+ "ConnectionAcquisitionMode.IMMEDIATELY; but ConnectionReleaseMode."
						+ releaseMode.name() + " was specified."
				);
			};
		};
	}
}

View on GitHub (pinned to fad1729dce)

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

Example fix

// before
settings.put("hibernate.connection.acquisition_mode", "IMMEDIATELY");
settings.put("hibernate.connection.release_mode", "AFTER_TRANSACTION"); // IllegalArgumentException at bootstrap

// after
settings.put("hibernate.connection.handling_mode", "IMMEDIATE_ACQUISITION_AND_HOLD");

Defensive patterns

Strategy: validation

Validate before calling

// fail fast with a clear message before bootstrapping
if (acquisition == org.hibernate.resource.jdbc.spi.ConnectionAcquisitionMode.IMMEDIATELY
        && release != org.hibernate.ConnectionReleaseMode.ON_CLOSE) {
  throw new IllegalStateException(
      "ConnectionAcquisitionMode.IMMEDIATELY requires ConnectionReleaseMode.ON_CLOSE");
}

Try / catch

catch (IllegalArgumentException e) {
  // bootstrap rejected the acquisition/release pairing: correct the config to a
  // canonical handling mode and rebuild — do not catch-and-continue in production
}

Prevention

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

When it happens

Trigger: 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.

Common situations: 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.

Related errors

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