{"record":{"id":"5b78961877e39aa8","repo":"hibernate/hibernate-orm","slug":"passed-attribute-name-s-did-not-correspond-to-a-5b7896","errorCode":null,"errorMessage":"Passed attribute name [%s] did not correspond to a collection (list) reference [%s] relative to %s","messagePattern":"Passed attribute name \\[(.+?)\\] did not correspond to a collection \\(list\\) 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":604,"sourceCode":"\t}\n\n\t@Nonnull\n\t@Override\n\t@SuppressWarnings(\"unchecked\")\n\tpublic <Y> SqmListJoin<T, Y> joinList(@Nonnull String attributeName, @Nonnull JoinType jt) {\n\t\tfinal var joinedPathSource = getReferencedPathSource().getSubPathSource( attributeName );\n\n\t\tif ( joinedPathSource instanceof ListPersistentAttribute ) {\n\t\t\tfinal var join = buildListJoin(\n\t\t\t\t\t(ListPersistentAttribute<T, Y>) 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 (list) 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 <K, V> SqmMapJoin<T, K, V> joinMap(@Nonnull String attributeName) {\n\t\treturn joinMap( attributeName, JoinType.INNER );\n\t}\n\n\t@Nonnull\n\t@Override","sourceCodeStart":586,"sourceCodeEnd":622,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/query/sqm/tree/spi/domain/AbstractSqmFrom.java#L586-L622","documentation":"AbstractSqmFrom.joinList(attributeName, joinType) requires a ListPersistentAttribute, i.e. a java.util.List mapped with @OrderColumn. A List mapped without @OrderColumn is modeled by Hibernate as a bag (BagPersistentAttribute), not a list, so joinList on it throws IllegalArgumentException.","triggerScenarios":"root.joinList(\"items\", JoinType.LEFT) when items is List<Item> without @OrderColumn (bag); joinList on Set/Collection/Map/singular attributes.","commonSituations":"The classic case: entity uses List<Order> orders with no @OrderColumn, and query code calls joinList because the Java type is a List; also removal of @OrderColumn during mapping cleanup breaking existing criteria queries.","solutions":["For a List without @OrderColumn use joinCollection(attributeName, joinType) instead.","If positional semantics are required, map the attribute with @OrderColumn so it becomes a true ListPersistentAttribute.","Use the typed overload join(ListAttribute) from the metamodel to make the mismatch a compile-time issue."],"exampleFix":"// before\ncustomerRoot.joinList( \"orders\", JoinType.INNER ); // List<Order> without @OrderColumn -> bag\n// after\ncustomerRoot.joinCollection( \"orders\", JoinType.INNER );","handlingStrategy":"type-guard","validationCode":null,"typeGuard":"static boolean isOrderedList(ManagedType<?> type, String attr) {\n    Attribute<?, ?> a = type.getAttribute( attr );\n    return a instanceof org.hibernate.metamodel.model.domain.ListPersistentAttribute; // @OrderColumn lists only\n}","tryCatchPattern":null,"preventionTips":["Remember: java.util.List without @OrderColumn is a bag in Hibernate — use joinCollection for it.","Guard joinList with a ListPersistentAttribute check (not just java.util.List in the Java type).","If positional list semantics are required, add @OrderColumn to the mapping."],"tags":["hibernate","criteria-api","join","list","bag","order-column"],"backgroundTag":"wrong-collection-join-type","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}