{"record":{"id":"d7514b44c4de3dc0","repo":"hibernate/hibernate-orm","slug":"property-not-known-d7514b","errorCode":null,"errorMessage":"Property not known: {}.{}","messagePattern":"Property not known: (.+?)\\.(.+?)","errorType":"exception","errorClass":"MappingException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/boot/internal/MetadataImpl.java","lineNumber":578,"sourceCode":"\t\tfinal var persistentClass = entityBindingMap.get( entityName );\n\t\tif ( persistentClass == null ) {\n\t\t\tthrow new MappingException( \"Persistent class not known: \" + entityName );\n\t\t}\n\t\tif ( !persistentClass.hasIdentifierProperty() ) {\n\t\t\treturn null;\n\t\t}\n\t\treturn persistentClass.getIdentifierProperty().getName();\n\t}\n\n\t@Override\n\tpublic org.hibernate.type.Type getReferencedPropertyType(String entityName, String propertyName) throws MappingException {\n\t\tfinal var persistentClass = entityBindingMap.get( entityName );\n\t\tif ( persistentClass == null ) {\n\t\t\tthrow new MappingException( \"Persistent class not known: \" + entityName );\n\t\t}\n\t\tfinal var referencedProperty = persistentClass.getReferencedProperty( propertyName );\n\t\tif ( referencedProperty == null ) {\n\t\t\tthrow new MappingException( \"Property not known: \" + entityName + '.' + propertyName );\n\t\t}\n\t\treturn referencedProperty.getType();\n\t}\n\n\t//Specific for copies only:\n\n\tpublic Map<String,PersistentClass> getEntityBindingMap() {\n\t\treturn entityBindingMap;\n\t}\n\n\tpublic Map<String, Collection> getCollectionBindingMap() {\n\t\treturn collectionBindingMap;\n\t}\n\n\tpublic Map<String, TypeDefinition> getTypeDefinitionMap() {\n\t\treturn typeDefinitionMap;\n\t}\n","sourceCodeStart":560,"sourceCodeEnd":596,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/boot/internal/MetadataImpl.java#L560-L596","documentation":"After the entity binding is found, MetadataImpl.getReferencedPropertyType calls persistentClass.getReferencedProperty(propertyName); when that returns null, Hibernate throws MappingException 'Property not known: <entity>.<property>'. It means the entity resolved, but no mapped property with that exact name exists on it. The property name must be the Java/Mapping property name, never the column name.","triggerScenarios":"Calling getReferencedPropertyType with a typo'd property name, a DB column name instead of the mapped property name, a field of a superclass mapped as @MappedSuperclass that is not a referenced property, or a nested embeddable path that getReferencedProperty does not resolve.","commonSituations":"Using COLUMN_NAME by mistake when the property is named differently via @Column(name=...); property renamed in the entity but not in caller; expecting embedded sub-attributes ('address.city') to resolve; property exists only on a subclass while the query targets the root entity name.","solutions":["Pass the mapped property name exactly as declared on the entity (field/getter name), not the column name","Confirm the property exists via sessionFactory.getMetamodel().entity(...).getAttributes() or persistentClass.getProperty(name)","For embedded values, target the embeddable property itself ('address') rather than the nested path","Check whether the property lives on a subclass; query the entity name that actually declares it"],"exampleFix":"// before: field is @Column(name = \"cust_id\") private Long customerId;\nType t = metadata.getReferencedPropertyType(\"Order\", \"cust_id\"); // MappingException\n\n// after: use the property name\nType t = metadata.getReferencedPropertyType(\"Order\", \"customerId\");","handlingStrategy":"validation","validationCode":"static boolean propertyExists(Metadata metadata, String entityName, String propertyName) {\n    PersistentClass pc = metadata.getEntityBindingMap().get(entityName);\n    return pc != null && pc.getProperty(propertyName) != null\n        || (pc != null && pc.getIdentifierProperty() != null\n            && pc.getIdentifierProperty().getName().equals(propertyName));\n}","typeGuard":null,"tryCatchPattern":"try {\n    Type t = metadata.getReferencedPropertyType(entityName, propertyName);\n} catch (MappingException e) {\n    if (e.getMessage() != null && e.getMessage().startsWith(\"Property not known\")) {\n        Set<String> attrs = new HashSet<>();\n        metadata.getEntityBindingMap().get(entityName)\n               .getPropertyIterator().forEachRemaining(p -> attrs.add(p.getName()));\n        throw new IllegalArgumentException(\"No property '\" + propertyName + \"'. Available: \" + attrs, e);\n    }\n    throw e;\n}","preventionTips":["Always use mapped property names, never column names, when calling metadata APIs","Validate property names against the JPA metamodel (entity(...).getAttributes()) in one central place","When entities are refactored, grep for string property references in metadata queries"],"tags":["hibernate","metadata","mapping","property-name"],"backgroundTag":"unknown-property-name","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}