{"record":{"id":"e034419a996e4db4","repo":"hibernate/hibernate-orm","slug":"persistent-class-not-known-e03441","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/MetadataImpl.java","lineNumber":553,"sourceCode":"\t}\n\n\t@Override\n\tpublic Component getGenericComponent(Class<?> componentClass) {\n\t\treturn genericComponentsMap.get( componentClass );\n\t}\n\n\t@Override\n\tpublic DiscriminatorType<?> resolveEmbeddableDiscriminatorType(\n\t\t\tClass<?> embeddableClass,\n\t\t\tSupplier<DiscriminatorType<?>> supplier) {\n\t\treturn embeddableDiscriminatorTypesMap.computeIfAbsent( embeddableClass, k -> supplier.get() );\n\t}\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\tif ( !persistentClass.hasIdentifierProperty() ) {\n\t\t\treturn null;\n\t\t}\n\t\treturn persistentClass.getIdentifierProperty().getName();\n\t}\n\n\t@Override\n\tpublic org.hibernate.type.Type getReferencedPropertyType(String entityName, String propertyName) throws MappingException {","sourceCodeStart":535,"sourceCodeEnd":571,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/boot/internal/MetadataImpl.java#L535-L571","documentation":"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.","triggerScenarios":"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.","commonSituations":"@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.","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)"],"exampleFix":"// before: entity is @Entity(name = \"User\") in package com.acme\nType idType = metadata.getIdentifierType(\"com.acme.User\"); // MappingException\n\n// after: use the registered entity name\nType idType = metadata.getIdentifierType(\"User\");","handlingStrategy":"validation","validationCode":"// before calling getIdentifierType, confirm the entity name is registered\nstatic boolean entityExists(SessionFactory sf, String entityName) {\n    return sf.unwrap(SessionFactoryImplementor.class)\n              .getMetamodel()\n              .entityPersisters()\n              .containsKey(entityName);\n}\n\nif (!entityExists(sf, \"User\")) throw new IllegalArgumentException(\"Unknown entity: User\");\nType idType = ((SessionImplementor) session).getFactory().getMetamodel()... ;","typeGuard":null,"tryCatchPattern":"try {\n    Type idType = metadata.getIdentifierType(entityName);\n} catch (MappingException e) {\n    if (e.getMessage().startsWith(\"Persistent class not known\")) {\n        // re-resolve: list candidates and fail with a helpful message\n        throw new IllegalArgumentException(\"Unknown entity '\" + entityName + \"'. Registered: \"\n            + sessionFactory.getMetamodel().getEntities(), e);\n    }\n    throw e;\n}","preventionTips":["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"],"tags":["hibernate","metadata","mapping","entity-name"],"backgroundTag":"unknown-entity-name","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}