{"record":{"id":"2a3ab12854aba435","repo":"hibernate/hibernate-orm","slug":"not-a-map-valued-attribute-node","errorCode":null,"errorMessage":"Not a Map-valued attribute node","messagePattern":"Not a Map-valued attribute node","errorType":"exception","errorClass":"UnsupportedOperationException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/graph/internal/AttributeNodeImpl.java","lineNumber":213,"sourceCode":"\t\treturn valueSubgraph;\n\t}\n\n\t@Override\n\t@Nonnull\n\tpublic SubGraphImplementor<J> addSingularSubgraph() {\n\t\tthrow new UnsupportedOperationException(\"Not a singular attribute node\");\n\t}\n\n\t@Override\n\t@Nonnull\n\tpublic SubGraphImplementor<E> addElementSubgraph() {\n\t\tthrow new UnsupportedOperationException( \"Not a collection-valued attribute node\" );\n\t}\n\n\t@Override\n\t@Nonnull\n\tpublic SubGraphImplementor<K> addKeySubgraph() {\n\t\tthrow new UnsupportedOperationException( \"Not a Map-valued attribute node\" );\n\t}\n\n\tprotected void checkToOne() {\n\t\tfinal Attribute.PersistentAttributeType attributeType = attribute.getPersistentAttributeType();\n\t\tif ( attributeType != MANY_TO_ONE && attributeType != ONE_TO_ONE && attributeType != EMBEDDED ) {\n\t\t\tthrow new CannotContainSubGraphException( \"Attribute '\" + attribute.getName() + \"' is not a to-one association\" );\n\t\t}\n\t}\n\n\tprotected void checkToMany() {\n\t\tfinal Attribute.PersistentAttributeType attributeType = attribute.getPersistentAttributeType();\n\t\tif ( attributeType != MANY_TO_MANY && attributeType != ONE_TO_MANY ) {\n\t\t\tthrow new CannotContainSubGraphException( \"Attribute '\" + attribute.getName() + \"' is not a to-many association\" );\n\t\t}\n\t}\n\n\tprotected <T> ManagedDomainType<T> asManagedType(DomainType<T> domainType) {\n\t\tif ( domainType instanceof ManagedDomainType<T> managedDomainType ) {","sourceCodeStart":195,"sourceCodeEnd":231,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/graph/internal/AttributeNodeImpl.java#L195-L231","documentation":"addKeySubgraph() is implemented only on MapAttributeNodeImpl — the node kind created for Map-valued attributes. Calling it on a singular node or a non-Map collection node hits the base-class implementation and throws UnsupportedOperationException.","triggerScenarios":"node.addKeySubgraph() where the attribute is a @OneToMany/@ManyToOne/List/Set/basic — anything that is not a persistent java.util.Map attribute.","commonSituations":"Adding key-fetching logic to graphs of collections that were Maps in an earlier iteration of the model; generic graph code that calls all three subgraph variants unconditionally.","solutions":["Use addKeySubgraph() only on Map attributes; fetch Map values with addElementSubgraph()","For non-map collections use addElementSubgraph()","Guard the call with attr instanceof MapAttribute before invoking"],"exampleFix":"// before\ngraph.addAttributeNode(\"tags\").addKeySubgraph(); // tags is List<String> → throws\n\n// after — key subgraphs exist only for Map attributes\ngraph.addAttributeNode(\"settings\")   // Map<Language, Setting>\n     .addKeySubgraph();                // Language key subgraph\ngraph.addAttributeNode(\"settings\")\n     .addElementSubgraph().addAttributeNode(\"value\");","handlingStrategy":"type-guard","validationCode":"if (isMap(node.getAttribute())) {\n    node.addKeySubgraph();      // keys\n    node.addElementSubgraph();  // values\n}","typeGuard":"static boolean isMap(Attribute<?, ?> attr) {\n    return attr instanceof jakarta.persistence.metamodel.MapAttribute<?, ?, ?>;\n}","tryCatchPattern":null,"preventionTips":["Call addKeySubgraph() only on Map persistent attributes","Fetch Map values with addElementSubgraph()","Check the metamodel kind before calling key/element subgraph methods in generic code"],"tags":["hibernate","entity-graph","map","key-subgraph","attribute-node","jpa"],"backgroundTag":"entity-graph-misuse","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}