hibernate/hibernate-orm · error · UnsupportedOperationException

Unsupported attempt to resolve JDBC type for Map.Entry

Error message

Unsupported attempt to resolve JDBC type for Map.Entry

What it means

MapEntryJavaType describes java.util.Map.Entry, which Hibernate uses internally for HQL entry() selections and map handling. A Map.Entry has no column representation, so any attempt to derive a recommended JDBC type for it — typically because a Map attribute was mapped as a basic collection — throws UnsupportedOperationException during bootstrap.

Source

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

/**
 * Descriptor for {@link Map.Entry}.
 *
 * @author Steve Ebersole
 */
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. Annotate Map fields of basic values with @ElementCollection (plus @MapKeyColumn/@Column as needed)
2. If keys or values are entities, use @ManyToMany with @MapKeyJoinColumn
3. Never expose Map.Entry as a persistent attribute — entry() belongs in queries only

Example fix

// before
@Entity class Config {
    Map<String, String> entries = new HashMap<>(); // treated as basic collection of Map.Entry -> throws
}

// after
@Entity class Config {
    @ElementCollection
    @MapKeyColumn(name = "cfg_key")
    @Column(name = "cfg_value")
    Map<String, String> entries = new HashMap<>();
}

static List<String> mapFieldsMissingAnnotations(Class<?> entity) {
    var bad = new ArrayList<String>();
    for (var f : entity.getDeclaredFields())
        if (java.util.Map.class.isAssignableFrom(f.getType())
            && !f.isAnnotationPresent(jakarta.persistence.ElementCollection.class)
            && !f.isAnnotationPresent(jakarta.persistence.ManyToMany.class)
            && !f.isAnnotationPresent(jakarta.persistence.Transient.class))
            bad.add(entity.getName() + "." + f.getName());
    return bad; // assert empty before buildSessionFactory()
}

try {
    sessionFactory = metadata.buildSessionFactory();
} catch (UnsupportedOperationException | org.hibernate.MappingException e) {
    // if the stack trace names MapEntryJavaType: add @ElementCollection to the map field
    throw new IllegalStateException("Map field unmapped: " + e.getMessage(), e);
}

When it happens

Trigger: A Map field without @ElementCollection/@ManyToMany so the map (element java type Map.Entry) is treated as one basic value; declaring an attribute of type Map.Entry directly; schema export or validation hitting such a field.

Common situations: New Map fields added to entities without relationship annotations; refactoring collections into Map shape; assuming Hibernate infers map semantics from the field type alone.

Related errors

• @TargetEmbeddable can only be specified on properties marked
• collection id mapping has wrong number of columns: " + getRo
• collection index mapping has wrong number of columns: " + ge
• Basic collection has element type '%s' which is not a known
• Error transforming element-collection :

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