What causes "Persistent class not known: {}" in hibernate/hibernate-orm?

Use the exact registered entity name: by default the unqualified class name, or the value of @Entity(name=...)

hibernate/hibernate-orm · error · MappingException

Persistent class not known: {}

Error message

Persistent class not known: {}

What it means

MetadataImpl.getIdentifierType(String entityName) resolves an entity's identifier type by looking the name up in the metadata entity-binding map. The exact entity name string must match what Hibernate registered; otherwise a MappingException 'Persistent class not known' is thrown. It is usually reached during SessionFactory creation or from code using the legacy Hibernate metadata APIs directly.

Source

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

	}

	@Override
	public Component getGenericComponent(Class<?> componentClass) {
		return genericComponentsMap.get( componentClass );
	}

	@Override
	public DiscriminatorType<?> resolveEmbeddableDiscriminatorType(
			Class<?> embeddableClass,
			Supplier<DiscriminatorType<?>> supplier) {
		return embeddableDiscriminatorTypesMap.computeIfAbsent( embeddableClass, k -> supplier.get() );
	}

	@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 );
		}
		if ( !persistentClass.hasIdentifierProperty() ) {
			return null;
		}
		return persistentClass.getIdentifierProperty().getName();
	}

	@Override
	public org.hibernate.type.Type getReferencedPropertyType(String entityName, String propertyName) throws MappingException {

View on GitHub (pinned to fad1729dce)

Solutions

Use the exact registered entity name: by default the unqualified class name, or the value of @Entity(name=...)
Print the registered names and compare: sessionFactory.getMetamodel().getEntities() and EntityType.getName()
Confirm the entity is actually in the persistence unit (persistence.xml <class> entry or package scanning)
If you hold the Java class, resolve the name instead of guessing: sessionFactory.getMetamodel().entity(MyEntity.class)

Example fix

// before: entity is @Entity(name = "User") in package com.acme
Type idType = metadata.getIdentifierType("com.acme.User"); // MappingException

// after: use the registered entity name
Type idType = metadata.getIdentifierType("User");

Defensive patterns

Strategy: validation

Validate before calling

// before calling getIdentifierType, confirm the entity name is registered
static boolean entityExists(SessionFactory sf, String entityName) {
    return sf.unwrap(SessionFactoryImplementor.class)
              .getMetamodel()
              .entityPersisters()
              .containsKey(entityName);
}

if (!entityExists(sf, "User")) throw new IllegalArgumentException("Unknown entity: User");
Type idType = ((SessionImplementor) session).getFactory().getMetamodel()... ;

Try / catch

try {
    Type idType = metadata.getIdentifierType(entityName);
} catch (MappingException e) {
    if (e.getMessage().startsWith("Persistent class not known")) {
        // re-resolve: list candidates and fail with a helpful message
        throw new IllegalArgumentException("Unknown entity '" + entityName + "'. Registered: "
            + sessionFactory.getMetamodel().getEntities(), e);
    }
    throw e;
}

Prevention

Derive entity names from the metamodel instead of hard-coding strings
Standardize on @Entity(name = ...) explicitly, or never use it — avoid mixed conventions
Write a startup assertion that every entity name your code queries exists in the metamodel

When it happens

Trigger: Calling metadata.getIdentifierType(entityName) with a name that is not a registered entity name: passing the fully-qualified class name when the entity is registered under @Entity(name=...) or the default unqualified class name, referencing an entity from a different persistence unit, or a typo in the name.

Common situations: @Entity(name = "usr") makes the entity name 'usr', not 'User' or 'com.acme.User'; entity class missing from persistence.xml or not scanned; code assumes class name equals entity name; entity mapping failed earlier so the binding was never added.

Related errors

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