hibernate/hibernate-orm · error · UnsupportedOperationException

Unsupported attempt to unwrap Map.Entry value

Error message

Unsupported attempt to unwrap Map.Entry value

What it means

Even when a Map.Entry value exists at runtime, Hibernate cannot convert it to any JDBC type: unwrap() on MapEntryJavaType throws UnsupportedOperationException. Map.Entry is a query-time projection (HQL entry(m)), not a storable or bindable value.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/type/descriptor/java/spi/MapEntryJavaType.java:36

 */
public class MapEntryJavaType extends AbstractClassJavaType<Map.Entry> {
	/**
	 * Singleton access
	 */
	public static final MapEntryJavaType INSTANCE = new MapEntryJavaType();

	public MapEntryJavaType() {
		super( Map.Entry.class );
	}

	@Override
	public JdbcType getRecommendedJdbcType(JdbcTypeIndicators context) {
		throw new UnsupportedOperationException( "Unsupported attempt to resolve JDBC type for Map.Entry" );
	}

	@Override
	public <X> X unwrap(Map.Entry value, Class<X> type, WrapperOptions options) {
		throw new UnsupportedOperationException( "Unsupported attempt to unwrap Map.Entry value" );
	}

	@Override
	public <X> Map.Entry wrap(X value, WrapperOptions options) {
		throw new UnsupportedOperationException( "Unsupported attempt to wrap Map.Entry value" );
	}
}

View on GitHub (pinned to fad1729dce)

Solutions

1. Extract key and value from the entry and bind them as separate parameters
2. Project a DTO ('select new Dto(key(m), value(m))') instead of entry(m) when results will be reused
3. Treat entry() results as read-only — never persist, cache or rebind them

Example fix

// before
var e = (Map.Entry<String, String>) session
        .createQuery("select entry(c.entries) from Config c").getSingleResult();
query.setParameter("p", e); // unwrap(Map.Entry) -> UnsupportedOperationException

// after
query.setParameter("k", e.getKey());
query.setParameter("v", e.getValue());

static boolean bindableParameterValue(Object v) {
    return !(v instanceof java.util.Map.Entry);
}
// guard generic binders: if (!bindableParameterValue(v)) decompose before setParameter

static boolean isMapEntryProjection(Object value) {
    return value instanceof java.util.Map.Entry;
} // if true: extract key/value — never persist or bind the entry itself

try {
    query.setParameter("p", value);
} catch (UnsupportedOperationException e) {
    if (value instanceof Map.Entry<?, ?> entry) {
        query.setParameter("k", entry.getKey());
        query.setParameter("v", entry.getValue());
    } else throw e;
}

When it happens

Trigger: Passing the result of 'select entry(m) from ...' back as a query parameter; custom types trying to unwrap Map.Entry for binding; caching or batching code that round-trips entry() results into other operations.

Common situations: DTO assembly that feeds HQL projections into further queries; generic parameter-binding helpers accepting arbitrary objects; test fixtures reusing query results as inputs.

Related errors

• Unknown unwrap conversion requested: " + type.getTypeName()
• Unwrap strategy not known for this Java type: " + getTypeNam
• Id not an instance of type " + type.getName()
• Unwrap strategy not known for this Java type: " + getTypeNam
• Unwrap strategy not known for this Java type: " + getTypeNam

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