hibernate/hibernate-orm · error · MappingException

Persistent class not known: {}

Error message

Persistent class not known: {}

What it means

getReferencedPropertyType(entityName, propertyName) first resolves the entity binding and throws MappingException('Persistent class not known') — note the capitalized 'Persistent' here, unlike the lowercase variant in the sibling methods — when entityBindingMap has no entry for that name. Same failure class as the other Mapping lookups: the entity name is wrong or the entity is not registered in this factory.

Source

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

		return persistentClass.getIdentifier().getType();
	}

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

View on GitHub (pinned to fad1729dce)

Solutions

1. Diff the failing name against metadata.getEntityBindings().keySet()
2. Correct the reference to the registered entity name
3. Register the missing entity in the same persistence unit
4. Stop deriving names heuristically (simple names, uppercase) — carry the registered entity name explicitly

Example fix

// before — simple name used where the FQN is registered
Type t = mapping.getReferencedPropertyType( "Customer", "ref" );

// after
Type t = mapping.getReferencedPropertyType( "com.acme.model.Customer", "ref" );

if ( metadata.getEntityBinding( entityName ) == null ) {
    throw new IllegalStateException( "Unknown entity name: " + entityName
            + "; registered names: " + metadata.getEntityBindings().keySet() );
}

static boolean isKnownEntity( Metadata metadata, String entityName ) {
    return entityName != null && metadata.getEntityBinding( entityName ) != null;
}

try {
    return mapping.getReferencedPropertyType( entityName, propertyName );
} catch ( MappingException e ) {
    if ( e.getMessage() != null && e.getMessage().contains( "Persistent class not known" ) ) {
        // note the capitalized 'Persistent' in this variant
        throw new IllegalArgumentException( "Unregistered entity: " + entityName, e );
    }
    throw e;
}

When it happens

Trigger: Resolving a referenced property type for an unregistered entity: association mappings or tooling referencing an entity by a stale or misspelled name, an entity from another persistence unit, or an interface/@MappedSuperclass name passed where an entity name is required.

Common situations: Refactors renaming entities or packages, persistence-unit splits after modularization, and custom code that derives entity names from class.getSimpleName() while Hibernate registers fully-qualified names.

Related errors

• persistent class not known: {}
• Property 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/f8bb6d294644e92d. Report an issue: GitHub.