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}(${value.getClass().getName()})] as int

What it means

ConfigurationHelper.getInt only accepts three shapes for a setting: null (use default), java.lang.Integer, or a String it can Integer.parseInt. Any other runtime type under the key (Long, Boolean, Double, enum, custom object) cannot be coerced, so Hibernate fails fast with this ConfigurationException instead of guessing. The message prints the offending key, its raw value, and the value's concrete class, so the bad entry is easy to locate.

Source

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

	 *
	 * @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;
		}
		else if (value instanceof Integer integer) {
			return integer;
		}
		else if (value instanceof String string) {
			return Integer.parseInt(string);
		}
		throw new ConfigurationException(
				"Could not determine how to handle configuration value [name=" + name +
						", value=" + value + "(" + value.getClass().getName() + ")] as int"
		);
	}

	/**
	 * Get the config value as an {@link Integer}
	 *
	 * @param name The config setting name.
	 * @param values The map of config values
	 *
	 * @return The value, or null if not found
	 */
	public static Integer getInteger(String name, Map<?,?> values) {
		final Object value = values.get( name );
		if ( value == null ) {
			return null;
		}

View on GitHub (pinned to fad1729dce)

Solutions

1. Store the value as an Integer (settings.put(key, 5000)) or as a numeric String (settings.put(key, "5000"))
2. If the value comes from a typed external source, convert with String.valueOf(...) before putting it into the Hibernate properties map
3. Read the message: it contains name=<key>, value=<raw value> and the value class - fix exactly that one entry

Example fix

// before
Map<String,Object> settings = new HashMap<>();
settings.put("hibernate.jdbc.fetch_size", 5_000L); // Long -> ConfigurationException

// after
settings.put("hibernate.jdbc.fetch_size", 5_000);   // Integer
// or
settings.put("hibernate.jdbc.fetch_size", "5000");  // numeric String

// Normalize the settings map before building the SessionFactory
for (Map.Entry<String,Object> e : settings.entrySet()) {
    Object v = e.getValue();
    if (!(v == null || v instanceof Integer || v instanceof String)) {
        e.setValue(String.valueOf(v)); // getInt parses numeric Strings
    }
}

static boolean isIntCoercible(Object v) {
    if (v == null || v instanceof Integer) return true;
    if (v instanceof String s) {
        try { Integer.parseInt(s.trim()); return true; }
        catch (NumberFormatException ignored) { }
    }
    return false;
}

When it happens

Trigger: Building a SessionFactory/EntityManagerFactory from a Map where a numeric setting was stored as a boxed Long or another Number, e.g. settings.put("hibernate.jdbc.fetch_size", 5_000L); or where a typed config source (YAML/microprofile config loader) delivers a Boolean/Double for a key Hibernate reads via getInt().

Common situations: Programmatic property maps using autoboxed long literals; typed configuration frameworks that parse "5000" into Long before it reaches Hibernate; copying properties between systems where the value type changes; unit tests injecting typed property values.

Related errors

• Could not determine how to handle configuration value [name=
• Could not determine how to handle configuration value [name=
• The {storageEngine} storage engine is not supported
• Unrecognized graph_parser_mode value : " + graphParserMode +
• Could not instantiate event listener '{}'

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