{"record":{"id":"ebc979938db036b7","repo":"hibernate/hibernate-orm","slug":"not-a-collection-valued-attribute-node","errorCode":null,"errorMessage":"Not a collection-valued attribute node","messagePattern":"Not a collection-valued attribute node","errorType":"exception","errorClass":"UnsupportedOperationException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/graph/internal/AttributeNodeImpl.java","lineNumber":207,"sourceCode":"\t\tverifyMutability();\n\t\tsetFetchType( FetchType.EAGER );\n\t\t// this one is intentionally lenient and disfavored\n\t\tif ( valueSubgraph == null ) {\n\t\t\tvalueSubgraph = new SubGraphImpl<>( asManagedType( valueGraphType ), true );\n\t\t}\n\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 ) {","sourceCodeStart":189,"sourceCodeEnd":225,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/graph/internal/AttributeNodeImpl.java#L189-L225","documentation":"addElementSubgraph() is implemented only on collection nodes (PluralAttributeNodeImpl and MapAttributeNodeImpl). Calling it on a node for a singular attribute — where there are no collection elements — falls through to the base-class implementation and throws UnsupportedOperationException.","triggerScenarios":"node.addElementSubgraph() on an attribute node for a @ManyToOne, @OneToOne, @Embedded or basic attribute; usually generic code that always uses the element variant regardless of attribute kind.","commonSituations":"Adopting the JPA 3.2 AttributeNode API uniformly across nodes; switching an association from to-many back to to-one; copy-paste between nodes of different kinds.","solutions":["Use addSingularSubgraph() (or addSubgraph()) for to-one/embedded attributes","Reserve addElementSubgraph() for collection and Map element subgraphs","Branch on attr instanceof PluralAttribute in generic graph builders"],"exampleFix":"// before\ngraph.addAttributeNode(\"customer\").addElementSubgraph(); // customer is @ManyToOne → throws\n\n// after\ngraph.addAttributeNode(\"customer\")\n     .addSingularSubgraph()\n     .addAttributeNode(\"address\");","handlingStrategy":"type-guard","validationCode":"if (isCollection(node.getAttribute())) {\n    node.addElementSubgraph().addAttributeNode(\"name\");\n}\nelse {\n    node.addSingularSubgraph().addAttributeNode(\"name\");\n}","typeGuard":"static boolean isCollection(Attribute<?, ?> attr) {\n    return attr instanceof jakarta.persistence.metamodel.PluralAttribute<?, ?, ?>;\n}","tryCatchPattern":null,"preventionTips":["Reserve addElementSubgraph() for collection/Map element subgraphs","When an association changes cardinality, update the graph-building code with it","Use static metamodel references so attribute kinds are visible at the call site"],"tags":["hibernate","entity-graph","element-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"}