{"record":{"id":"f061d6e36404528a","repo":"hibernate/hibernate-orm","slug":"identifier-field-named-in-mapsid-does-not","errorCode":null,"errorMessage":"Identifier field '{}' named in '@MapsId' does not exist in entity '{}'","messagePattern":"Identifier field '(.+?)' named in '@MapsId' does not exist in entity '(.+?)'","errorType":"exception","errorClass":"AnnotationException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/boot/model/internal/AnnotatedJoinColumns.java","lineNumber":244,"sourceCode":"\t\telse {\n\t\t\tfor ( var joinColumn : joinColumns ) {\n\t\t\t\tbuildExplicitJoinTableJoinColumn( parent, propertyHolder, inferredData, joinColumn );\n\t\t\t}\n\t\t}\n\t\thandlePropertyRef( inferredData.getAttributeMember(), parent );\n\t\treturn parent;\n\t}\n\n\tProperty resolveMapsId() {\n\t\tfinal var persistentClass = getPropertyHolder().getPersistentClass();\n\t\tfinal var identifier = persistentClass.getIdentifier();\n\t\ttry {\n\t\t\treturn identifier instanceof Component embeddedIdType\n\t\t\t\t\t? embeddedIdType.getProperty( mapsId )   // an @EmbeddedId\n\t\t\t\t\t: persistentClass.getProperty( mapsId );  // a simple id or an @IdClass\n\t\t}\n\t\tcatch (MappingException me) {\n\t\t\tthrow new AnnotationException( \"Identifier field '\" + mapsId\n\t\t\t\t\t+ \"' named in '@MapsId' does not exist in entity '\" + persistentClass.getEntityName() + \"'\",\n\t\t\t\t\tme );\n\t\t}\n\t}\n\n\tpublic List<AnnotatedJoinColumn> getJoinColumns() {\n\t\treturn columns;\n\t}\n\n\t@Override\n\tpublic void addColumn(AnnotatedColumn child) {\n\t\tif ( !( child instanceof AnnotatedJoinColumn joinColumn ) ) {\n\t\t\tthrow new AssertionFailure( \"wrong sort of column\" );\n\t\t}\n\t\taddColumn( joinColumn );\n\t}\n\n\tpublic void addColumn(AnnotatedJoinColumn child) {","sourceCodeStart":226,"sourceCodeEnd":262,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/boot/model/internal/AnnotatedJoinColumns.java#L226-L262","documentation":"'@MapsId(\"fieldName\")' names an attribute that must be part of the entity's identifier — a field of an @EmbeddedId class or the simple/@IdClass id property. resolveMapsId() looked it up via persistentClass.getIdentifier()/getProperty(mapsId) and caught a MappingException because no such identifier attribute exists, so the derived-id mapping cannot be wired.","triggerScenarios":"'@MapsId(\"userId\")' on an association when the entity's @EmbeddedId class has no 'userId' field; a typo or case mismatch in the mapsId value; using the Java field name of the association itself instead of the id attribute; @MapsId on an entity whose id is @GeneratedValue with a different property name.","commonSituations":"Renames during refactoring that change the embeddable's field but not the @MapsId string; switching between @IdClass and @EmbeddedId without updating mapsId values; following derived-id examples and mistaking the FK property for the id property.","solutions":["Match the @MapsId value EXACTLY (case-sensitive) to an attribute of the @EmbeddedId embeddable, or to the simple id property name.","If the id is a simple @Id field, either omit the value ('@MapsId' with no argument) or use the id field's name.","Re-run the bootstrap (test that builds a SessionFactory) after every rename of identifier fields."],"exampleFix":"// before\n@Embeddable\nclass OrderId implements Serializable {\n    Long number; // no 'id' field\n}\n\n@Entity\nclass Shipment {\n    @EmbeddedId OrderId id;\n\n    @ManyToOne(fetch = FetchType.LAZY)\n    @MapsId(\"id\") // does not exist in OrderId\n    Order order;\n}\n\n// after\n@Entity\nclass Shipment {\n    @EmbeddedId OrderId id;\n\n    @ManyToOne(fetch = FetchType.LAZY)\n    @MapsId(\"number\")\n    Order order;\n}","handlingStrategy":"validation","validationCode":"// Guard: @MapsId value must be a field of the embedded id (or the simple id)\nfor (Field f : cls.getDeclaredFields()) {\n    MapsId mapsId = f.getAnnotation(MapsId.class);\n    if (mapsId != null && !mapsId.value().isEmpty()) {\n        Field idField = cls.getDeclaredField(\"id\");\n        Class<?> idType = idField.getType();\n        if (idType.isAnnotationPresent(Embeddable.class)\n                && Arrays.stream(idType.getDeclaredFields())\n                         .noneMatch(x -> x.getName().equals(mapsId.value()))) {\n            throw new IllegalStateException(\"@MapsId(\" + mapsId.value()\n                + \") is not an attribute of \" + idType.getSimpleName());\n        }\n    }\n}","typeGuard":null,"tryCatchPattern":"try {\n    Metadata md = sources.buildMetadata();\n} catch (AnnotationException e) {\n    // 'Identifier field ... does not exist' -> fix the mapsId string to match the id attribute\n    throw newConfigurationException(\"Bad @MapsId target\", e);\n}","preventionTips":["Treat @MapsId values like stringly-typed references: update them in the same change-set as id field renames.","For simple ids, prefer the no-arg '@MapsId' form.","Assert one SessionFactory bootstrap test per persistence unit in CI."],"tags":["hibernate","jpa","mapsid","embedded-id","orm-mapping"],"backgroundTag":"mapsid-misconfiguration","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}