hibernate/hibernate-orm · error · HibernateException

Unknown unwrap conversion requested: " + type.getTypeName()

Error message

Unknown unwrap conversion requested: " + type.getTypeName() + " to " + conversionType.getName()

What it means

AbstractJavaType.unknownUnwrap is the fallback used by JavaType.unwrap(value, conversionType, options) when a descriptor does not support unwrapping its values to the requested Java class. It signals that a value must be converted to a type for which no conversion path is defined on that descriptor.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/type/descriptor/java/AbstractJavaType.java:88

	}

	@Override
	public boolean areEqual(T one, T another) {
		return Objects.equals( one, another );
	}

	@Override
	public Comparator<T> getComparator() {
		return comparator;
	}

	@Override
	public String extractLoggableRepresentation(T value) {
		return (value == null) ? "null" : value.toString();
	}

	protected HibernateException unknownUnwrap(Class<?> conversionType) {
		throw new HibernateException(
				"Unknown unwrap conversion requested: " + type.getTypeName() + " to " + conversionType.getName()
		);
	}

	protected HibernateException unknownWrap(Class<?> conversionType) {
		throw new HibernateException(
				"Unknown wrap conversion requested: " + conversionType.getName() + " to " + type.getTypeName()
		);
	}
}

View on GitHub (pinned to fad1729dce)

Solutions

Pass values of the attribute's declared type (or types its JavaType explicitly supports)
Extend the custom JavaType's unwrap() to handle the requested conversionType
Prefer an AttributeConverter for domain<->relational conversion instead of ad-hoc unwrap calls
If the mismatch is on a query parameter, bind with an explicit type: setParameter(name, value, type)

Example fix

// before
public class MoneyJavaType extends AbstractClassJavaType<Money> {
    @Override
    public <X> X unwrap(Money value, Class<X> type, WrapperOptions options) {
        if (type == String.class) return (X) value.asString();
        return unknownUnwrap(type); // fails for BigDecimal
    }
}
// after
@Override
public <X> X unwrap(Money value, Class<X> type, WrapperOptions options) {
    if (type == String.class) return (X) value.asString();
    if (type == BigDecimal.class) return (X) value.amount();
    return unknownUnwrap(type);
}

Defensive patterns

Strategy: type-guard

Validate before calling

// before passing a foreign value to a typed parameter, check convertibility
Object v = /* candidate */;
Class<?> expected = String.class; // parameter's Java type
if (!expected.isInstance(v) && !(v instanceof Number) && !(v instanceof java.util.Date)) {
    v = String.valueOf(v); // explicit conversion instead of relying on unwrap
}

Type guard

// in a custom JavaType: enumerate supported targets and check before unwrap
private static final Set<Class<?>> SUPPORTED = Set.of(String.class, Integer.class, BigDecimal.class);

@SuppressWarnings("unchecked")
static <X> boolean canUnwrap(Class<X> type) { return SUPPORTED.contains(type); }

Try / catch

try {
    query.setParameter("code", value);
} catch (HibernateException e) {
    if (String.valueOf(e.getMessage()).contains("Unknown unwrap conversion requested")) {
        query.setParameter("code", convertToExpectedType(value)); // retry once with the right type
    } else throw e;
}

Prevention

Always bind values of the attribute's declared type
Cover String, toString-able and JDBC types in custom unwrap() implementations
Keep an integration test per custom JavaType exercising bind + read
Use AttributeConverter for domain conversions rather than ad-hoc unwrap reliance

When it happens

Trigger: Binding or reading a value through a JavaType whose unwrap() only supports specific targets: e.g. a custom JavaType that handles String/Integer but receives a request to unwrap to java.sql.Date, or passing a value of the wrong type to setParameter so Hibernate tries to unwrap the value's descriptor to the parameter's JDBC-expected Java type.

Common situations: Custom JavaType implementations that override unwrap() without covering all needed target types; passing a LocalDate to a parameter mapped as String (or similar mismatches); result extraction where the driver returns a type the descriptor cannot unwrap; upgrading Hibernate versions where additional unwrap paths started being requested.

Related errors

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