{"record":{"id":"58ad701a88d411e3","repo":"hibernate/hibernate-orm","slug":"unsupported-attempt-to-resolve-jdbc-type-for-map-e","errorCode":null,"errorMessage":"Unsupported attempt to resolve JDBC type for Map.Entry","messagePattern":"Unsupported attempt to resolve JDBC type for Map\\.Entry","errorType":"exception","errorClass":"UnsupportedOperationException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/type/descriptor/java/spi/MapEntryJavaType.java","lineNumber":31,"sourceCode":"\n/**\n * Descriptor for {@link Map.Entry}.\n *\n * @author Steve Ebersole\n */\npublic class MapEntryJavaType extends AbstractClassJavaType<Map.Entry> {\n\t/**\n\t * Singleton access\n\t */\n\tpublic static final MapEntryJavaType INSTANCE = new MapEntryJavaType();\n\n\tpublic MapEntryJavaType() {\n\t\tsuper( Map.Entry.class );\n\t}\n\n\t@Override\n\tpublic JdbcType getRecommendedJdbcType(JdbcTypeIndicators context) {\n\t\tthrow new UnsupportedOperationException( \"Unsupported attempt to resolve JDBC type for Map.Entry\" );\n\t}\n\n\t@Override\n\tpublic <X> X unwrap(Map.Entry value, Class<X> type, WrapperOptions options) {\n\t\tthrow new UnsupportedOperationException( \"Unsupported attempt to unwrap Map.Entry value\" );\n\t}\n\n\t@Override\n\tpublic <X> Map.Entry wrap(X value, WrapperOptions options) {\n\t\tthrow new UnsupportedOperationException( \"Unsupported attempt to wrap Map.Entry value\" );\n\t}\n}\n","sourceCodeStart":13,"sourceCodeEnd":44,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/type/descriptor/java/spi/MapEntryJavaType.java#L13-L44","documentation":"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.","triggerScenarios":"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.","commonSituations":"New Map fields added to entities without relationship annotations; refactoring collections into Map shape; assuming Hibernate infers map semantics from the field type alone.","solutions":["Annotate Map fields of basic values with @ElementCollection (plus @MapKeyColumn/@Column as needed)","If keys or values are entities, use @ManyToMany with @MapKeyJoinColumn","Never expose Map.Entry as a persistent attribute — entry() belongs in queries only"],"exampleFix":"// before\n@Entity class Config {\n    Map<String, String> entries = new HashMap<>(); // treated as basic collection of Map.Entry -> throws\n}\n\n// after\n@Entity class Config {\n    @ElementCollection\n    @MapKeyColumn(name = \"cfg_key\")\n    @Column(name = \"cfg_value\")\n    Map<String, String> entries = new HashMap<>();\n}","handlingStrategy":"validation","validationCode":"static List<String> mapFieldsMissingAnnotations(Class<?> entity) {\n    var bad = new ArrayList<String>();\n    for (var f : entity.getDeclaredFields())\n        if (java.util.Map.class.isAssignableFrom(f.getType())\n            && !f.isAnnotationPresent(jakarta.persistence.ElementCollection.class)\n            && !f.isAnnotationPresent(jakarta.persistence.ManyToMany.class)\n            && !f.isAnnotationPresent(jakarta.persistence.Transient.class))\n            bad.add(entity.getName() + \".\" + f.getName());\n    return bad; // assert empty before buildSessionFactory()\n}","typeGuard":null,"tryCatchPattern":"try {\n    sessionFactory = metadata.buildSessionFactory();\n} catch (UnsupportedOperationException | org.hibernate.MappingException e) {\n    // if the stack trace names MapEntryJavaType: add @ElementCollection to the map field\n    throw new IllegalStateException(\"Map field unmapped: \" + e.getMessage(), e);\n}","preventionTips":["Every persistent Map needs @ElementCollection or @ManyToMany","Review mapping diffs when adding Map fields","Use entry()/key()/value() in queries only, never as attribute java types"],"tags":["hibernate","orm","map","mapping","element-collection"],"backgroundTag":"hibernate-mapping-exception","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}