{"record":{"id":"a907539db0d10081","repo":"hibernate/hibernate-orm","slug":"unknown-entity-type-a90753","errorCode":null,"errorMessage":"Unknown entity type '{}'","messagePattern":"Unknown entity type '(.+?)'","errorType":"exception","errorClass":"UnknownEntityTypeException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/metamodel/model/domain/internal/MappingMetamodelImpl.java","lineNumber":350,"sourceCode":"\t\treturn this;\n\t}\n\n\tpublic ServiceRegistry getServiceRegistry() {\n\t\treturn jpaMetamodel.getServiceRegistry();\n\t}\n\n\t@Override\n\tpublic void forEachEntityDescriptor(Consumer<EntityPersister> action) {\n\t\tfor ( var value : entityPersisterMap.values() ) {\n\t\t\taction.accept( value );\n\t\t}\n\t}\n\n\t@Override\n\tpublic EntityPersister getEntityDescriptor(String entityName) {\n\t\tfinal var entityPersister = entityPersisterMap.get( entityName );\n\t\tif ( entityPersister == null ) {\n\t\t\tthrow new UnknownEntityTypeException( entityName );\n\t\t}\n\t\treturn entityPersister;\n\t}\n\n\t@Override\n\tpublic EntityPersister getEntityDescriptor(NavigableRole name) {\n\t\tthrow new UnsupportedOperationException();\n\t}\n\n\t@Override\n\tpublic EmbeddableValuedModelPart getEmbeddableValuedModelPart(NavigableRole role){\n\t\tfinal var embeddableMappingType = embeddableValuedModelPart.get( role );\n\t\tif ( embeddableMappingType == null ) {\n\t\t\tthrow new IllegalArgumentException( \"Unable to locate EmbeddableValuedModelPart: \" + role );\n\t\t}\n\t\treturn embeddableMappingType;\n\t}\n","sourceCodeStart":332,"sourceCodeEnd":368,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/metamodel/model/domain/internal/MappingMetamodelImpl.java#L332-L368","documentation":"MappingMetamodelImpl.getEntityDescriptor(String) looks the persister up by JPA entity name in entityPersisterMap; a miss throws UnknownEntityTypeException with the given name. This backs every name-based runtime API: HQL 'from X', session.get(\"X\", id), loaders, filters, and cache APIs.","triggerScenarios":"session.get(\"Customer\", id) or HQL 'from Customer' where the entity is registered under a different name; using the fully-qualified class name when the default registration is the unqualified name; typo or case mismatch in the entity name string.","commonSituations":"@Entity(name=\"CUST\") renames that leave stale string references in queries/code; teams assuming FQN is accepted; names copied from a different persistence unit or module; string-based loaders in configuration files drifting from the mapping.","solutions":["Use the registered entity name: default is the unqualified class name, otherwise the @Entity(name=...) value","List the actual names from the metamodel and compare: emf.getMetamodel().getEntities().forEach(e -> System.out.println(e.getName()))","Prefer the class-based variants (session.find(Class, id), typed HQL) so names are checked at compile time"],"exampleFix":"// before\nObject o = session.get(\"com.acme.Customer\", 1L); // UnknownEntityTypeException\n\n// after\n@Entity(name = \"CUST\") public class Customer {...}\nObject o = session.get(\"CUST\", 1L);\n// or, compile-safe:\nCustomer c = session.get(Customer.class, 1L);","handlingStrategy":"validation","validationCode":"Set<String> entityNames = emf.getMetamodel().getEntities().stream()\n    .map(EntityType::getName)\n    .collect(Collectors.toSet());\nif (!entityNames.contains(entityName)) {\n  throw new IllegalArgumentException(\n      \"No entity named '\" + entityName + \"'. Registered names: \" + entityNames);\n}\nObject o = session.get(entityName, id); // safe now","typeGuard":null,"tryCatchPattern":"try {\n  Object o = session.get(entityName, id);\n} catch (UnknownEntityTypeException e) {\n  // log registered names to pinpoint the mismatch\n  throw new IllegalArgumentException(\"Unknown entity name '\" + entityName\n      + \"'; known: \" + emf.getMetamodel().getEntities().stream().map(EntityType::getName).toList(), e);\n}","preventionTips":["Prefer class-based lookups (session.get(Class, id)) and typed HQL so entity names are compile-checked","Centralize entity-name strings as constants derived from @Entity(name=...) values","When you must use string names, validate against the metamodel name set once at startup"],"tags":["hibernate","jpa","entity-name","runtime-lookup"],"backgroundTag":"unknown-entity-name","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}