hibernate/hibernate-orm · error · ConfigurationException

Could not determine how to handle configuration raw [name=${

Error message

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

What it means

ConfigurationHelper.getBoolean(name, values, default) resolves a setting from the configuration map. toBoolean accepts exactly three things: null (yields the default), a Boolean, and a String (parsed case-insensitively via Boolean.parseBoolean, which never fails). Any other runtime type — Integer, Long, enum, AtomicBoolean, a custom object — returns null from toBoolean and this method converts that into a ConfigurationException naming the offending setting and raw value.

Source

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

	 */
	public static boolean getBoolean(String name, Map<?,?> values) {
		return getBoolean( name, values, false );
	}

	/**
	 * Get the config value as a boolean.
	 *
	 * @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 boolean getBoolean(String name, Map<?,?> values, boolean defaultValue) {
		final Object raw = values.get( name );
		final Boolean value = toBoolean( raw, defaultValue );
		if ( value == null ) {
			throw new ConfigurationException(
					"Could not determine how to handle configuration raw [name=" + name + ", value=" + raw + "] as boolean"
			);
		}
		else {
			return value;
		}
	}

	public static Boolean toBoolean(Object value, boolean defaultValue) {
		if ( value == null ) {
			return defaultValue;
		}
		else if (value instanceof Boolean bool) {
			return bool;
		}
		else if (value instanceof String string) {
			return Boolean.parseBoolean(string);
		}

View on GitHub (pinned to fad1729dce)

Solutions

Read the message: it names the setting and the raw value that failed — fix that map entry first
Store boolean settings only as String ("true"/"false") or Boolean
Normalize the whole property map before passing it to Hibernate: convert every value to String
Audit YAML/env-to-Properties loaders that map flags to integers

Example fix

// before
Map<String, Object> props = new HashMap<>();
props.put( "hibernate.show_sql", 1 ); // Integer -> ConfigurationException
// after
props.put( "hibernate.show_sql", "true" );

Defensive patterns

Strategy: validation

Validate before calling

// Normalize a config map before handing it to Hibernate
static Map<String, Object> normalizeBooleans(Map<String, Object> props, Set<String> booleanKeys) {
    for ( String key : booleanKeys ) {
        Object v = props.get( key );
        if ( v != null && !( v instanceof Boolean ) && !( v instanceof String ) ) {
            props.put( key, String.valueOf( v ) ); // let Boolean.parseBoolean handle it
        }
    }
    return props;
}

Type guard

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

Try / catch

try {
    boolean flag = ConfigurationHelper.getBoolean( name, values, false );
} catch ( ConfigurationException e ) {
    // message contains name + raw value: normalize that entry and retry bootstrap
}

Prevention

Type all Hibernate properties as String at the configuration source ("true"/"false")
Beware env-var/YAML bridges that hand over Integer flags like 0/1
Validate the property map once at startup instead of debugging mid-bootstrap failures

When it happens

Trigger: A configuration map containing a non-Boolean/non-String value for a boolean setting, e.g. props.put("hibernate.show_sql", 1) or an enum/Optional-typed value, when Hibernate (or code calling ConfigurationHelper.getBoolean) reads it during bootstrap.

Common situations: Programmatically assembled EntityManagerFactory/SessionFactory property maps with numeric flags (0/1) copied from YAML/env config; typed configuration objects whose getters return int; wrappers that inject boxed types instead of strings; note the exception message gives you the exact property name and value.

Related errors

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