{"record":{"id":"40f9606ec35f024d","repo":"hibernate/hibernate-orm","slug":"persistent-class-not-known","errorCode":null,"errorMessage":"persistent class not known: {}","messagePattern":"persistent class not known: (.+?)","errorType":"exception","errorClass":"MappingException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/boot/internal/InFlightMetadataCollectorImpl.java","lineNumber":987,"sourceCode":"\t\t\t\t\t\t\t\tnamespace,\n\t\t\t\t\t\t\t\tphysicalTableName,\n\t\t\t\t\t\t\t\tisAbstract,\n\t\t\t\t\t\t\t\tincludedTable\n\t\t\t\t\t\t)\n\t\t\t\t);\n\t\t\t}\n\t\t}\n\t}\n\n\n\t// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\t// Mapping impl\n\n\t@Override\n\tpublic org.hibernate.type.Type getIdentifierType(String entityName) throws MappingException {\n\t\tfinal var persistentClass = entityBindingMap.get( entityName );\n\t\tif ( persistentClass == null ) {\n\t\t\tthrow new MappingException( \"persistent class not known: \" + entityName );\n\t\t}\n\t\treturn persistentClass.getIdentifier().getType();\n\t}\n\n\t@Override\n\tpublic String getIdentifierPropertyName(String entityName) throws MappingException {\n\t\tfinal var persistentClass = entityBindingMap.get( entityName );\n\t\tif ( persistentClass == null ) {\n\t\t\tthrow new MappingException( \"persistent class not known: \" + entityName );\n\t\t}\n\t\treturn persistentClass.hasIdentifierProperty()\n\t\t\t\t? persistentClass.getIdentifierProperty().getName()\n\t\t\t\t: null;\n\t}\n\n\t@Override\n\tpublic org.hibernate.type.Type getReferencedPropertyType(String entityName, String propertyName) throws MappingException {\n\t\tfinal var persistentClass = entityBindingMap.get( entityName );","sourceCodeStart":969,"sourceCodeEnd":1005,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/boot/internal/InFlightMetadataCollectorImpl.java#L969-L1005","documentation":"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=...).","triggerScenarios":"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.","commonSituations":"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.","solutions":["Log the registered entity names (metadata.getEntityBindings().keySet()) and diff against the name in the message","Fix the reference: correct the entity-name in the mapping, or add @Entity so the target class is picked up","Ensure the target class is part of the same persistence unit (listed in persistence.xml or scanned by the same factory)","Use the exact registered name — @Entity(name=...) overrides the default fully-qualified class name"],"exampleFix":"<!-- before: typo in the referenced entity-name -->\n<many-to-one name=\"owner\" class=\"com.acme.Usr\"/>\n\n<!-- after -->\n<many-to-one name=\"owner\" class=\"com.acme.User\"/>","handlingStrategy":"type-guard","validationCode":"if ( metadata.getEntityBinding( entityName ) == null ) {\n    throw new IllegalStateException( \"Unknown entity name: \" + entityName\n            + \"; registered names: \" + metadata.getEntityBindings().keySet() );\n}","typeGuard":"static boolean isKnownEntity( Metadata metadata, String entityName ) {\n    return entityName != null && metadata.getEntityBinding( entityName ) != null;\n}","tryCatchPattern":"try {\n    return mapping.getIdentifierType( entityName );\n} catch ( MappingException e ) {\n    if ( e.getMessage() != null && e.getMessage().contains( \"persistent class not known\" ) ) {\n        // name-vs-registration mismatch: log the registered names and fix the caller\n        throw new IllegalArgumentException( \"Unregistered entity: \" + entityName, e );\n    }\n    throw e;\n}","preventionTips":["Keep one module owning entity names and export them as constants","Validate entity names against metadata before calling Mapping APIs","Boot the whole persistence unit in an integration test to catch stale references"],"tags":["hibernate","orm","java","bootstrap","entity-mapping"],"backgroundTag":"unknown-entity-name","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}