hibernate/hibernate-orm · error · MappingException

persistent class not known: {}

Error message

persistent class not known: {}

What it means

getIdentifierType(entityName) is part of the Mapping surface used while finalizing mappings and by tooling (schema generation, Envers, custom Mapping consumers). It looks the entity up in entityBindingMap and throws MappingException when no binding is registered under that exact name. In practice the name is wrong: a typo, a class outside the persistence unit, an interface/@MappedSuperclass name, or a renamed @Entity(name=...).

Source

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

								namespace,
								physicalTableName,
								isAbstract,
								includedTable
						)
				);
			}
		}
	}


	// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
	// Mapping impl

	@Override
	public org.hibernate.type.Type getIdentifierType(String entityName) throws MappingException {
		final var persistentClass = entityBindingMap.get( entityName );
		if ( persistentClass == null ) {
			throw new MappingException( "persistent class not known: " + entityName );
		}
		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 );

View on GitHub (pinned to fad1729dce)

Solutions

1. Log the registered entity names (metadata.getEntityBindings().keySet()) and diff against the name in the message
2. Fix the reference: correct the entity-name in the mapping, or add @Entity so the target class is picked up
3. Ensure the target class is part of the same persistence unit (listed in persistence.xml or scanned by the same factory)
4. Use the exact registered name — @Entity(name=...) overrides the default fully-qualified class name

Example fix

<!-- before: typo in the referenced entity-name -->
<many-to-one name="owner" class="com.acme.Usr"/>

<!-- after -->
<many-to-one name="owner" class="com.acme.User"/>

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.getIdentifierType( entityName );
} catch ( MappingException e ) {
    if ( e.getMessage() != null && e.getMessage().contains( "persistent class not known" ) ) {
        // name-vs-registration mismatch: log the registered names and fix the caller
        throw new IllegalArgumentException( "Unregistered entity: " + entityName, e );
    }
    throw e;
}

When it happens

Trigger: Referencing an entity name that is not a registered binding: hbm.xml entity-name typos, association targets excluded from the persistence unit, tooling asking for the unqualified name while only the qualified name is registered (or vice versa), @Entity(name=...) renames not propagated.

Common situations: Splitting a monolith so a target entity lands in another module; renaming @Entity(name) while XML still uses the old name; passing a Java interface or mapped superclass instead of the entity class; dynamic-map entity-name mismatches.

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/40f9606ec35f024d. Report an issue: GitHub.