{"record":{"id":"693b927ee70d788f","repo":"hibernate/hibernate-orm","slug":"property-not-known","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/InFlightMetadataCollectorImpl.java","lineNumber":1011,"sourceCode":"\tpublic String getIdentifierPropertyName(String entityName) 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\treturn persistentClass.hasIdentifierProperty()\n\t\t\t\t? persistentClass.getIdentifierProperty().getName()\n\t\t\t\t: null;\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\n\tprivate final Map<Identifier,Identifier> logicalToPhysicalTableNameMap = new HashMap<>();\n\tprivate final Map<Identifier,Identifier> physicalToLogicalTableNameMap = new HashMap<>();\n\n\t@Override\n\tpublic void addTableNameBinding(Identifier logicalName, Table table) {\n\t\tlogicalToPhysicalTableNameMap.put( logicalName, table.getNameIdentifier() );\n\t\tphysicalToLogicalTableNameMap.put( table.getNameIdentifier(), logicalName );\n\t}\n\n\t@Override\n\tpublic void addTableNameBinding(String schema, String catalog, String logicalName, String realTableName, Table denormalizedSuperTable) {\n\t\tfinal Identifier logicalNameIdentifier = getDatabase().toIdentifier( logicalName );\n\t\tfinal Identifier physicalNameIdentifier = getDatabase().toIdentifier( realTableName );","sourceCodeStart":993,"sourceCodeEnd":1029,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/boot/internal/InFlightMetadataCollectorImpl.java#L993-L1029","documentation":"After the entity binding is found, persistentClass.getReferencedProperty(propertyName) returned null, so Hibernate reports 'Property not known: Entity.prop'. This Mapping-level lookup resolves property references made by other mappings — property-ref in hbm.xml and referenced property names in association mappings — and fails when that property does not exist on the referenced entity.","triggerScenarios":"hbm.xml property-ref pointing at a property that does not exist; association references using a property name that was renamed; the referenced property living on a different class in the hierarchy after a refactor into @MappedSuperclass; custom Mapping consumers passing arbitrary property names.","commonSituations":"Renaming a Java field without updating mappedBy/property-ref in XML; moving fields between an entity and its mapped superclass; hand-maintained hbm.xml drifting from the Java model after refactors.","solutions":["Open the entity named in the message and verify the property exists, including inherited fields","Update the referencing mapping to the current property name","If the property moved up a hierarchy, confirm the entity still exposes it through the whole closure","Replace hbm.xml property-ref with explicit @JoinColumn mappings, which are validated earlier and with clearer messages"],"exampleFix":"<!-- before: property renamed in Java from 'email' to 'contactEmail' -->\n<many-to-one name=\"primary\" class=\"Contact\" property-ref=\"email\"/>\n\n<!-- after -->\n<many-to-one name=\"primary\" class=\"Contact\" property-ref=\"contactEmail\"/>","handlingStrategy":"validation","validationCode":"final PersistentClass pc = metadata.getEntityBinding( entityName );\nboolean known = false;\nif ( pc != null ) {\n    final Iterator<?> it = pc.getPropertyIterator();\n    while ( it.hasNext() ) {\n        if ( propertyName.equals( ( (Property) it.next() ).getName() ) ) {\n            known = true;\n            break;\n        }\n    }\n}\nif ( !known ) {\n    throw new IllegalStateException( \"Unknown property \" + entityName + '.' + propertyName );\n}","typeGuard":"static boolean hasProperty( Metadata metadata, String entityName, String property ) {\n    final PersistentClass pc = metadata.getEntityBinding( entityName );\n    if ( pc == null ) {\n        return false;\n    }\n    final Iterator<?> it = pc.getPropertyIterator();\n    while ( it.hasNext() ) {\n        if ( property.equals( ( (Property) it.next() ).getName() ) ) {\n            return true;\n        }\n    }\n    return false;\n}","tryCatchPattern":"try {\n    return mapping.getReferencedPropertyType( entityName, propertyName );\n} catch ( MappingException e ) {\n    if ( e.getMessage() != null && e.getMessage().contains( \"Property not known\" ) ) {\n        throw new IllegalArgumentException( \"No property '\" + propertyName + \"' on entity '\" + entityName + \"'\", e );\n    }\n    throw e;\n}","preventionTips":["Update property-ref/mappedBy values in the same commit that renames fields","Prefer explicit @JoinColumn over hbm.xml property-ref","Search mappings for old property names after every entity refactor"],"tags":["hibernate","orm","java","bootstrap","entity-mapping","property-mapping"],"backgroundTag":"unknown-property-mapping","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}