hibernate/hibernate-orm · error · IllegalArgumentException

Null value passed to convert

Error message

Null value passed to convert

What it means

WrapperArrayHandling.interpretExternalSetting(Object) (WrapperArrayHandling.java:56-58) converts the raw value of the hibernate.type.wrapper_array_handling property into the enum, and rejects a null input with IllegalArgumentException 'Null value passed to convert'. 'Null' here means the key was present in the configuration map with a null value (or null was passed programmatically) - an absent key never reaches this method. The lenient sibling interpretExternalSettingLeniently exists for optional resolutions.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/type/WrapperArrayHandling.java:61

	 * @see CharacterArrayJavaType
	 *
	 * @implNote The pre-6.2 behavior
	 * @apiNote Hibernate recommends users who want the legacy semantic change the domain model to use
	 * {@code byte[]} and {@code char[]} rather than using this setting.
	 */
	LEGACY,

	/**
	 * Hibernate will pick between {@linkplain #ALLOW} and {@linkplain #LEGACY} depending on
	 * whether the Dialect supports SQL {@code ARRAY} types.
	 *
	 * @implNote The default if {@linkplain AvailableSettings#JPA_COMPLIANCE JPA compliance} is enabled.
	 */
	PICK;

	public static WrapperArrayHandling interpretExternalSetting(Object value) {
		if ( value == null ) {
			throw new IllegalArgumentException( "Null value passed to convert" );
		}

		return value instanceof WrapperArrayHandling wrapperArrayHandling
				? wrapperArrayHandling
				: valueOf( value.toString().toUpperCase( Locale.ROOT ) );
	}

	/**
	 * Form of {@link #interpretExternalSetting(Object)} which allows incoming {@code null} values and
	 * simply returns {@code null}.  Useful for chained resolutions
	 */
	public static WrapperArrayHandling interpretExternalSettingLeniently(@Nullable Object value) {
		if ( value == null ) {
			return null;
		}

		return value instanceof WrapperArrayHandling wrapperArrayHandling
				? wrapperArrayHandling

View on GitHub (pinned to fad1729dce)

Solutions

  1. Remove the null-valued entry from the configuration map so the key is absent rather than null.
  2. In code that reads optional settings, use interpretExternalSettingLeniently(value), which returns null for null input.
  3. Set an explicit valid value: ALLOW, LEGACY, or PICK (uppercase; interpretation uses valueOf on the uppercased string).
  4. Sanitize properties before passing them to EntityManagerFactory setup: drop entries whose value is null.

Example fix

// before
Map<String, Object> props = new HashMap<>();
props.put("hibernate.type.wrapper_array_handling",
         System.getProperty("hibernate.type.wrapper_array_handling")); // null when unset

// after
String v = System.getProperty("hibernate.type.wrapper_array_handling");
if (v != null) {
    props.put("hibernate.type.wrapper_array_handling", v);
}
Defensive patterns

Strategy: validation

Validate before calling

// Strip null-valued Hibernate settings before bootstrap
props.entrySet().removeIf(e -> e.getValue() == null);
// or, when reading optional settings in your own code:
WrapperArrayHandling h = value == null
    ? null
    : WrapperArrayHandling.interpretExternalSettingLeniently(value);

Try / catch

try {
    return WrapperArrayHandling.interpretExternalSetting(value);
} catch (IllegalArgumentException e) {
    if ("Null value passed to convert".equals(e.getMessage())) {
        return WrapperArrayHandling.PICK; // document this default choice
    }
    throw e;
}

Prevention

When it happens

Trigger: Configuration map containing hibernate.type.wrapper_array_handling -> null (e.g. properties.put(key, System.getProperty(key)) where the system property is unset); Spring Environment resolving the key to null but still registering it in JPA properties; custom bootstrap code calling WrapperArrayHandling.interpretExternalSetting(null); spreadsheets/CI variables that define the key with an empty expansion that later becomes null.

Common situations: Property files with 'hibernate.type.wrapper_array_handling=' handled as null by a custom loader; conditional configuration code that adds the key whenever a feature flag exists without checking the value; copying settings between environments where one env omits the value; libraries wrapping Hibernate settings that preserve null entries.

Related errors

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