What causes "Property not known: {}.{}" in hibernate/hibernate-orm?

Pass the mapped property name exactly as declared on the entity (field/getter name), not the column name

hibernate/hibernate-orm · error · MappingException

Property not known: {}.{}

Error message

Property not known: {}.{}

What it means

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.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/boot/internal/MetadataImpl.java:578

		final var persistentClass = entityBindingMap.get( entityName );
		if ( persistentClass == null ) {
			throw new MappingException( "Persistent class not known: " + entityName );
		}
		if ( !persistentClass.hasIdentifierProperty() ) {
			return null;
		}
		return persistentClass.getIdentifierProperty().getName();
	}

	@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();
	}

	//Specific for copies only:

	public Map<String,PersistentClass> getEntityBindingMap() {
		return entityBindingMap;
	}

	public Map<String, Collection> getCollectionBindingMap() {
		return collectionBindingMap;
	}

	public Map<String, TypeDefinition> getTypeDefinitionMap() {
		return typeDefinitionMap;
	}

View on GitHub (pinned to fad1729dce)

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

Example fix

// before: field is @Column(name = "cust_id") private Long customerId;
Type t = metadata.getReferencedPropertyType("Order", "cust_id"); // MappingException

// after: use the property name
Type t = metadata.getReferencedPropertyType("Order", "customerId");

Defensive patterns

Strategy: validation

Validate before calling

static boolean propertyExists(Metadata metadata, String entityName, String propertyName) {
    PersistentClass pc = metadata.getEntityBindingMap().get(entityName);
    return pc != null && pc.getProperty(propertyName) != null
        || (pc != null && pc.getIdentifierProperty() != null
            && pc.getIdentifierProperty().getName().equals(propertyName));
}

Try / catch

try {
    Type t = metadata.getReferencedPropertyType(entityName, propertyName);
} catch (MappingException e) {
    if (e.getMessage() != null && e.getMessage().startsWith("Property not known")) {
        Set<String> attrs = new HashSet<>();
        metadata.getEntityBindingMap().get(entityName)
               .getPropertyIterator().forEachRemaining(p -> attrs.add(p.getName()));
        throw new IllegalArgumentException("No property '" + propertyName + "'. Available: " + attrs, e);
    }
    throw e;
}

Prevention

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

When it happens

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

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

Related errors

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