hibernate/hibernate-orm · error · MappingException

Property not known: {}.{}

Error message

Property not known: {}.{}

What it means

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.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/boot/internal/InFlightMetadataCollectorImpl.java:1011

	public String getIdentifierPropertyName(String entityName) throws MappingException {
		final var persistentClass = entityBindingMap.get( entityName );
		if ( persistentClass == null ) {
			throw new MappingException( "persistent class not known: " + entityName );
		}
		return persistentClass.hasIdentifierProperty()
				? persistentClass.getIdentifierProperty().getName()
				: null;
	}

	@Override
	public org.hibernate.type.Type getReferencedPropertyType(String entityName, String propertyName) throws MappingException {
		final var persistentClass = entityBindingMap.get( entityName );
		if ( persistentClass == null ) {
			throw new MappingException( "Persistent class not known: " + entityName );
		}
		final var referencedProperty = persistentClass.getReferencedProperty( propertyName );
		if ( referencedProperty == null ) {
			throw new MappingException( "Property not known: " + entityName + '.' + propertyName );
		}
		return referencedProperty.getType();
	}


	private final Map<Identifier,Identifier> logicalToPhysicalTableNameMap = new HashMap<>();
	private final Map<Identifier,Identifier> physicalToLogicalTableNameMap = new HashMap<>();

	@Override
	public void addTableNameBinding(Identifier logicalName, Table table) {
		logicalToPhysicalTableNameMap.put( logicalName, table.getNameIdentifier() );
		physicalToLogicalTableNameMap.put( table.getNameIdentifier(), logicalName );
	}

	@Override
	public void addTableNameBinding(String schema, String catalog, String logicalName, String realTableName, Table denormalizedSuperTable) {
		final Identifier logicalNameIdentifier = getDatabase().toIdentifier( logicalName );
		final Identifier physicalNameIdentifier = getDatabase().toIdentifier( realTableName );

View on GitHub (pinned to fad1729dce)

Solutions

1. Open the entity named in the message and verify the property exists, including inherited fields
2. Update the referencing mapping to the current property name
3. If the property moved up a hierarchy, confirm the entity still exposes it through the whole closure
4. Replace hbm.xml property-ref with explicit @JoinColumn mappings, which are validated earlier and with clearer messages

Example fix

<!-- before: property renamed in Java from 'email' to 'contactEmail' -->
<many-to-one name="primary" class="Contact" property-ref="email"/>

<!-- after -->
<many-to-one name="primary" class="Contact" property-ref="contactEmail"/>

final PersistentClass pc = metadata.getEntityBinding( entityName );
boolean known = false;
if ( pc != null ) {
    final Iterator<?> it = pc.getPropertyIterator();
    while ( it.hasNext() ) {
        if ( propertyName.equals( ( (Property) it.next() ).getName() ) ) {
            known = true;
            break;
        }
    }
}
if ( !known ) {
    throw new IllegalStateException( "Unknown property " + entityName + '.' + propertyName );
}

static boolean hasProperty( Metadata metadata, String entityName, String property ) {
    final PersistentClass pc = metadata.getEntityBinding( entityName );
    if ( pc == null ) {
        return false;
    }
    final Iterator<?> it = pc.getPropertyIterator();
    while ( it.hasNext() ) {
        if ( property.equals( ( (Property) it.next() ).getName() ) ) {
            return true;
        }
    }
    return false;
}

try {
    return mapping.getReferencedPropertyType( entityName, propertyName );
} catch ( MappingException e ) {
    if ( e.getMessage() != null && e.getMessage().contains( "Property not known" ) ) {
        throw new IllegalArgumentException( "No property '" + propertyName + "' on entity '" + entityName + "'", e );
    }
    throw e;
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• persistent class not known: {}
• Persistent class not known: {}
• Named query definition is null
• Named query definition name is null: %s
• Duplicate named query '%s'

AI-assisted analysis of hibernate/hibernate-orm@fad1729dce (2026-08-22). Data as JSON: /api/errors/693b927ee70d788f. Report an issue: GitHub.