hibernate/hibernate-orm · error · ConfigurationException

Could not determine how to handle configuration value

Error message

Could not determine how to handle configuration value [name=${name}, value=${value}(${value.getClass().getName()})] as long

What it means

ConfigurationHelper.getLong accepts only null, java.lang.Long, or a parseable String. Unlike getInt it does NOT accept Integer - only `value instanceof Long` is checked - so a perfectly reasonable boxed Integer value throws this ConfigurationException. Everything else (Boolean, Double, Integer, custom types) also fails fast with the key, raw value, and value class in the message.

Solutions

1. Store the value as a Long literal (settings.put(key, 3_600L)) or as a numeric String (settings.put(key, "3600"))
2. If the source value is an int primitive/Integer, widen it explicitly: settings.put(key, (long) intValue)
3. Use the message's name=<key>, value=<raw value>, class info to find and fix the exact entry

Example fix

// before
settings.put("some.long.setting", 3_600);  // autoboxes to Integer -> ConfigurationException

// after
settings.put("some.long.setting", 3_600L);   // Long
// or
settings.put("some.long.setting", "3600");   // numeric String

for (Map.Entry<String,Object> e : settings.entrySet()) {
    Object v = e.getValue();
    if (v instanceof Integer i) {
        e.setValue(i.longValue()); // getLong rejects Integer
    }
}

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

When it happens

Trigger: settings.put("<long-typed setting>", 3_600) where the literal autoboxes to Integer; or a typed config source delivering any Number that is not exactly Long; only "3600"-style Strings or 3_600L pass.

Common situations: Autoboxing surprises: writing a bare int literal for a long-typed setting; mixing properties between getInt-based and getLong-based consumers; refactors that change a literal from 100L to 100.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• Could not determine how to handle configuration value
• Could not determine how to handle configuration value
• Could not determine how to handle configuration raw
• Could not determine how to handle configuration value
• Could not determine ResourceLocalTransactionAccess to use…

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

Appendix: source

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

		throw new ConfigurationException(
				"Could not determine how to handle configuration value [name=" + name +
						", value=" + value + "(" + value.getClass().getName() + ")] as Integer"
		);
	}

	public static long getLong(String name, Map<?,?> values, int defaultValue) {
		final Object value = values.get( name );
		if ( value == null ) {
			return defaultValue;
		}
		else if (value instanceof Long number) {
			return number;
		}
		else if (value instanceof String string) {
			return Long.parseLong(string);
		}
		else {
			throw new ConfigurationException(
					"Could not determine how to handle configuration value [name=" + name +
							", value=" + value + "(" + value.getClass().getName() + ")] as long"
			);
		}
	}

	/**
	 * Replace a property value with a starred version
	 *
	 * @param properties properties to check
	 * @param key property to mask
	 *
	 * @return cloned and masked properties
	 */
	public static Properties maskOut(Properties properties, String key) {
		final var clone = (Properties) properties.clone();
		if ( clone.get( key ) != null ) {
			clone.setProperty( key, "****" );

View on GitHub (pinned to fad1729dce)