{"record":{"id":"6f8f78c98a22ce52","repo":"hibernate/hibernate-orm","slug":"passed-attribute-name-s-did-not-correspond-to-a-6f8f78","errorCode":null,"errorMessage":"Passed attribute name [%s] did not correspond to a collection (map) reference [%s] relative to %s","messagePattern":"Passed attribute name \\[(.+?)\\] did not correspond to a collection \\(map\\) reference \\[(.+?)\\] relative to (.+?)","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/query/sqm/tree/spi/domain/AbstractSqmFrom.java","lineNumber":637,"sourceCode":"\t}\n\n\t@Nonnull\n\t@Override\n\t@SuppressWarnings(\"unchecked\")\n\tpublic <K, V> SqmMapJoin<T, K, V> joinMap(@Nonnull String attributeName, @Nonnull JoinType jt) {\n\t\tfinal var joinedPathSource = getReferencedPathSource().getSubPathSource( attributeName );\n\n\t\tif ( joinedPathSource instanceof MapPersistentAttribute<?, ?, ?> ) {\n\t\t\tfinal var join = buildMapJoin(\n\t\t\t\t\t(MapPersistentAttribute<T, K, V>) joinedPathSource,\n\t\t\t\t\tSqmJoinType.from( jt ),\n\t\t\t\t\tfalse\n\t\t\t);\n\t\t\taddSqmJoin( join );\n\t\t\treturn join;\n\t\t}\n\n\t\tthrow new IllegalArgumentException(\n\t\t\t\tString.format(\n\t\t\t\t\t\tLocale.ROOT,\n\t\t\t\t\t\t\"Passed attribute name [%s] did not correspond to a collection (map) reference [%s] relative to %s\",\n\t\t\t\t\t\tattributeName,\n\t\t\t\t\t\tjoinedPathSource,\n\t\t\t\t\t\tgetNavigablePath()\n\t\t\t\t)\n\t\t);\n\t}\n\n\t@Nonnull\n\t@Override\n\tpublic <R> SqmEntityJoin<T, R> join(@Nonnull Class<R> entityJavaType) {\n\t\treturn join( nodeBuilder().getDomainModel().entity( entityJavaType ) );\n\t}\n\n\t@Nonnull\n\t@Override","sourceCodeStart":619,"sourceCodeEnd":655,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/query/sqm/tree/spi/domain/AbstractSqmFrom.java#L619-L655","documentation":"AbstractSqmFrom.joinMap(attributeName, joinType) requires the resolved attribute to be a MapPersistentAttribute (java.util.Map mapping with key/value semantics). Any other plural or singular kind throws IllegalArgumentException naming the attribute, the resolved source and the navigable path.","triggerScenarios":"root.joinMap(\"translations\", JoinType.INNER) when translations is Collection/List/Set; joinMap on a @ManyToOne or basic attribute.","commonSituations":"Changing a Map field to a List during refactoring; generic code assuming map semantics; keys modeled via @MapKey and then the field changed to a collection type.","solutions":["Use joinCollection/joinSet/joinList/join matching the actual container type.","Use the typed overload join(MapAttribute) from the metamodel for compile-time safety.","Check the metamodel attribute kind before choosing the method."],"exampleFix":"// before\nproductRoot.joinMap( \"specs\", JoinType.LEFT ); // specs is List<Spec>\n// after\nproductRoot.joinList( \"specs\", JoinType.LEFT );","handlingStrategy":"type-guard","validationCode":null,"typeGuard":"static boolean isMap(ManagedType<?> type, String attr) {\n    return type.getAttribute( attr ) instanceof jakarta.persistence.metamodel.MapAttribute;\n}","tryCatchPattern":null,"preventionTips":["Use the typed join(MapAttribute) overload when the metamodel object is available.","Check the attribute kind before string-based joinMap in generic builders.","After refactoring Map fields to other containers, update the corresponding join method."],"tags":["hibernate","criteria-api","join","map","illegal-argument"],"backgroundTag":"wrong-collection-join-type","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}