{"record":{"id":"f8bb6d294644e92d","repo":"hibernate/hibernate-orm","slug":"persistent-class-not-known-f8bb6d","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":1007,"sourceCode":"\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 );\n\t\tif ( persistentClass == null ) {\n\t\t\tthrow new MappingException( \"Persistent class not known: \" + entityName );\n\t\t}\n\t\tfinal var referencedProperty = persistentClass.getReferencedProperty( propertyName );\n\t\tif ( referencedProperty == null ) {\n\t\t\tthrow new MappingException( \"Property not known: \" + entityName + '.' + propertyName );\n\t\t}\n\t\treturn referencedProperty.getType();\n\t}\n\n\n\tprivate final Map<Identifier,Identifier> logicalToPhysicalTableNameMap = new HashMap<>();\n\tprivate final Map<Identifier,Identifier> physicalToLogicalTableNameMap = new HashMap<>();\n\n\t@Override\n\tpublic void addTableNameBinding(Identifier logicalName, Table table) {\n\t\tlogicalToPhysicalTableNameMap.put( logicalName, table.getNameIdentifier() );\n\t\tphysicalToLogicalTableNameMap.put( table.getNameIdentifier(), logicalName );\n\t}\n","sourceCodeStart":989,"sourceCodeEnd":1025,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/boot/internal/InFlightMetadataCollectorImpl.java#L989-L1025","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Diff the failing name against metadata.getEntityBindings().keySet()","Correct the reference to the registered entity name","Register the missing entity in the same persistence unit","Stop deriving names heuristically (simple names, uppercase) — carry the registered entity name explicitly"],"exampleFix":"// before — simple name used where the FQN is registered\nType t = mapping.getReferencedPropertyType( \"Customer\", \"ref\" );\n\n// after\nType t = mapping.getReferencedPropertyType( \"com.acme.model.Customer\", \"ref\" );","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.getReferencedPropertyType( entityName, propertyName );\n} catch ( MappingException e ) {\n    if ( e.getMessage() != null && e.getMessage().contains( \"Persistent class not known\" ) ) {\n        // note the capitalized 'Persistent' in this variant\n        throw new IllegalArgumentException( \"Unregistered entity: \" + entityName, e );\n    }\n    throw e;\n}","preventionTips":["Resolve entity bindings through metadata.getEntityBinding with an explicit check","Keep entity names stable across persistence units via shared constants","Add a startup assertion that all referenced entity names are registered"],"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"}