hibernate/hibernate-orm · error · ConfigurationException

Could not determine how to handle configuration value [name=

Error message

Could not determine how to handle configuration value [name=${name}, value=${value}] as boolean

What it means

ConfigurationHelper.getBooleanWrapper(name, values, default) is the Boolean-returning variant used for optional boolean settings. It accepts only null (default), Boolean, and String (via Boolean.valueOf — any string parses, unknown ones become false). Any other type — Integer, enum, custom object — triggers this ConfigurationException with the setting name and value inline.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/internal/util/config/ConfigurationHelper.java:170

	 *
	 * @param name The config setting name.
	 * @param values The map of config values
	 *
	 * @return The value.
	 */
	public static Boolean getBooleanWrapper(String name, Map<?,?> values, Boolean defaultValue) {
		final Object value = values.get( name );
		if ( value == null ) {
			return defaultValue;
		}
		else if (value instanceof Boolean bool) {
			return bool;
		}
		else if (value instanceof String string) {
			return Boolean.valueOf(string);
		}
		else {
			throw new ConfigurationException(
					"Could not determine how to handle configuration value [name=" + name + ", value=" + value + "] as boolean"
			);
		}
	}

	/**
	 * Get the config value as an int
	 *
	 * @param name The config setting name.
	 * @param values The map of config values
	 * @param defaultValue The default value to use if not found
	 *
	 * @return The value.
	 */
	public static int getInt(String name, Map<?,?> values, int defaultValue) {
		final Object value = values.get( name );
		if ( value == null ) {
			return defaultValue;

View on GitHub (pinned to fad1729dce)

Solutions

Use the name/value in the message to locate and fix the exact entry
Keep every value in Hibernate property maps either String or Boolean
Sanitize third-party config maps: value != null ? value.toString() : null before bootstrap
Add a startup assertion that validates boolean-typed settings in your own config layer

Example fix

// before
props.put( "hibernate.format_sql", 1 );
// after
props.put( "hibernate.format_sql", Boolean.TRUE );
// or defensive normalization for arbitrary sources
props.replaceAll( (k, v) -> v == null || v instanceof String || v instanceof Boolean ? v : v.toString() );

Defensive patterns

Strategy: validation

Validate before calling

// Reject or coerce non-Boolean/non-String values up front
static void validateBooleanSetting(String name, Map<?, ?> values) {
    Object v = values.get( name );
    if ( v != null && !( v instanceof Boolean ) && !( v instanceof String ) ) {
        throw new ConfigurationException( name + " must be Boolean or String, got: " + v.getClass().getName() );
    }
}

Type guard

static boolean isBooleanConfigValue(Object v) {
    return v == null || v instanceof Boolean || v instanceof String;
}

Try / catch

try {
    Boolean flag = ConfigurationHelper.getBooleanWrapper( name, values, null );
} catch ( ConfigurationException e ) {
    // the message names the offending setting: convert that value to String and rebuild
}

Prevention

Keep EntityManagerFactory property maps homogeneous: String (or Boolean) values only
When merging Spring/env/YAML sources, stringify every value before bootstrap
Write a config-validation unit test that runs the whole property map through type checks

When it happens

Trigger: Calling getBooleanWrapper (or bootstrapping Hibernate with a setting it reads this way) where the config map holds a non-Boolean/non-String value, e.g. props.put("hibernate.format_sql", Boolean.TRUE) is fine but props.put(..., 1) or an AtomicInteger/enum value throws.

Common situations: Typed config sources feeding the EntityManagerFactory properties map (Spring Environment resolves some values to Integer/enum); environment-variable bridges that produce Integers; tests building properties programmatically with the wrong boxed type.

Related errors

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