{"record":{"id":"36132c1b858278c9","repo":"hibernate/hibernate-orm","slug":"unable-to-locate-idclass-attributes","errorCode":null,"errorMessage":"Unable to locate IdClass attributes [{}]","messagePattern":"Unable to locate IdClass attributes \\[(.+?)\\]","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/metamodel/model/domain/internal/AbstractIdentifiableType.java","lineNumber":232,"sourceCode":"\t\t\tvisitIdClassAttributes( attributes::add );\n\t\t\treturn attributes.isEmpty() ? null : attributes;\n\t\t}\n\t\telse {\n\t\t\treturn null;\n\t\t}\n\t}\n\n\t@Override\n\t@Nonnull\n\tpublic Set<SingularAttribute<? super J, ?>> getIdClassAttributes() {\n\t\tif ( !hasIdClass() ) {\n\t\t\tthrow new IllegalArgumentException( \"This class [\" + getJavaType() + \"] does not define an IdClass\" );\n\t\t}\n\n\t\tfinal Set<SingularAttribute<? super J, ?>> attributes = new HashSet<>();\n\t\tvisitIdClassAttributes( attributes::add );\n\t\tif ( attributes.isEmpty() ) {\n\t\t\tthrow new IllegalArgumentException( \"Unable to locate IdClass attributes [\" + getJavaType() + \"]\" );\n\t\t}\n\t\treturn attributes;\n\t}\n\n\t@Override\n\tpublic void visitIdClassAttributes(@Nonnull Consumer<SingularPersistentAttribute<? super J, ?>> attributeConsumer) {\n\t\tif ( nonAggregatedIdAttributes != null ) {\n\t\t\tnonAggregatedIdAttributes.forEach( attributeConsumer );\n\t\t}\n\t\telse {\n\t\t\tfinal var superType = getSuperType();\n\t\t\tif ( superType != null ) {\n\t\t\t\t//noinspection rawtypes, unchecked\n\t\t\t\tsuperType.visitIdClassAttributes( (Consumer) attributeConsumer );\n\t\t\t}\n\t\t}\n\t}\n","sourceCodeStart":214,"sourceCodeEnd":250,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/metamodel/model/domain/internal/AbstractIdentifiableType.java#L214-L250","documentation":"The entity is annotated with @IdClass (hasIdClass() is true), but visiting its attributes collected zero members into nonAggregatedIdAttributes — Hibernate cannot find the id attributes that the @IdClass promises. This signals broken mapping metadata: the id-class fields and the entity's @Id fields do not line up, or attributes were never registered.","triggerScenarios":"An @IdClass entity where the id-class field names/types do not match the entity's @Id fields; programmatic/generateable mappings that declare an id class without marking the corresponding attributes as ids; bootstrap ordering issues during metamodel construction.","commonSituations":"Typos between @IdClass field names and entity @Id fields; changing field names in the id class only; using lombok/bytecode enhancement that renames or hides fields; Hibernate version upgrades changing id-class discovery rules.","solutions":["Make every field of the @IdClass a public @Id field on the entity with the same name and type","Give the @IdClass a no-arg constructor and correct equals/hashCode (spec requirement) and re-verify startup validation","Prefer @EmbeddedId — same composite semantics, fewer matching rules, and getId()/getIdType() then work"],"exampleFix":"// before\nclass OrderId implements Serializable { Long customerNbr; Date orderDay; } // names differ\n@Entity @IdClass(OrderId.class)\nclass Order { @Id Long customerNumber; @Id Date orderDate; } // -> empty id-class attributes\n\n// after\nclass OrderId implements Serializable { Long customerNumber; Date orderDate; } // match names+types","handlingStrategy":"validation","validationCode":"// At startup, verify @IdClass fields match @Id fields on the entity\nClass<?> idClass = /* from @IdClass */;\nfor (Field f : idClass.getDeclaredFields()) {\n    Field entityField = entityClass.getDeclaredField(f.getName()); // NoSuchElementException = mismatch\n    if (!entityField.isAnnotationPresent(Id.class)) throw new IllegalStateException(\"not @Id: \" + f.getName());\n    if (!f.getType().equals(entityField.getType())) throw new IllegalStateException(\"type mismatch: \" + f.getName());\n}","typeGuard":null,"tryCatchPattern":"try {\n    return type.getIdClassAttributes();\n} catch (IllegalArgumentException e) {\n    if (e.getMessage() != null && e.getMessage().contains(\"Unable to locate IdClass attributes\")) {\n        // mapping defect: @IdClass fields do not line up with entity @Id fields\n        throw new IllegalStateException(\"Broken @IdClass mapping on \" + type.getTypeName(), e);\n    }\n    throw e;\n}","preventionTips":["Keep @IdClass field names and types byte-identical to the entity's @Id fields","Give id classes a no-arg constructor and implement equals/hashCode","Consider @EmbeddedId to avoid the matching rules entirely","Add a startup unit test per composite-key entity that calls getIdClassAttributes()"],"tags":["hibernate","jpa-metamodel","idclass","mapping-error","composite-key"],"backgroundTag":"jpa-idclass-field-mismatch","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}