{"record":{"id":"72222f25d5773703","repo":"hibernate/hibernate-orm","slug":"id-not-an-instance-of-type-type-getname","errorCode":null,"errorMessage":"Id not an instance of type \" + type.getName()","messagePattern":"Id not an instance of type \" \\+ type\\.getName\\(\\)","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/type/descriptor/java/spi/EntityJavaType.java","lineNumber":68,"sourceCode":"\t\tfinal var lazyInitializer = extractLazyInitializer( value );\n\t\tfinal var javaTypeClass = getJavaTypeClass();\n\t\tif ( lazyInitializer != null ) {\n\t\t\treturn javaTypeClass.isAssignableFrom( lazyInitializer.getPersistentClass() )\n\t\t\t\t|| javaTypeClass.isAssignableFrom( lazyInitializer.getImplementationClass() );\n\t\t}\n\t\telse {\n\t\t\treturn javaTypeClass.isAssignableFrom( value.getClass() );\n\t\t}\n\t}\n\n\t@Override\n\tpublic <X> X unwrap(T value, Class<X> type, WrapperOptions options) {\n\t\tfinal var id =\n\t\t\t\toptions.getSessionFactory().getMappingMetamodel()\n\t\t\t\t\t\t.getEntityDescriptor( getJavaTypeClass() )\n\t\t\t\t\t\t.getIdentifier( value );\n\t\tif ( !type.isInstance( id ) ) {\n\t\t\tthrow new IllegalArgumentException( \"Id not an instance of type \" + type.getName() );\n\t\t}\n\t\treturn type.cast( value );\n\t}\n\n\t@Override\n\tpublic <X> T wrap(X value, WrapperOptions options) {\n\t\tfinal var entityClass = getJavaTypeClass();\n\t\tfinal var persister =\n\t\t\t\toptions.getSessionFactory().getMappingMetamodel()\n\t\t\t\t\t\t.getEntityDescriptor( entityClass );\n\t\tfinal var idType = persister.getIdentifierType().getReturnedClass();\n\t\tif ( !idType.isInstance( value ) ) {\n\t\t\tthrow new IllegalArgumentException( \"Not an instance of id type \" + idType.getName() );\n\t\t}\n\t\tfinal var entity =\n\t\t\t\toptions.getSession()\n\t\t\t\t\t\t.internalLoad( persister.getEntityName(), value, false, true );\n\t\treturn entityClass.cast( entity );","sourceCodeStart":50,"sourceCodeEnd":86,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/type/descriptor/java/spi/EntityJavaType.java#L50-L86","documentation":"EntityJavaType unwraps an entity reference to its identifier when the value must be bound to JDBC. It extracts the id via the entity persister, checks the requested target type with type.isInstance(id), and throws IllegalArgumentException when the binder's expected class differs from the entity's actual identifier class (e.g. String requested but the id is Long, or the id is composite).","triggerScenarios":"Binding a whole entity as a query parameter where the JDBC binder unwraps it to an id class that does not match; unwrap() calls with a wrong Class on an entity-typed attribute; @IdClass/@EmbeddedId composite ids flowing into single-column bind paths; custom types requesting an id class the entity does not use.","commonSituations":"Switching an @Id field from Long to a custom value object or UUID without updating consumers; native queries binding entities instead of ids; entity hierarchies where getIdentifier() returns a different runtime class than integrations assume.","solutions":["Bind the identifier explicitly — use entity.getId() as the parameter value instead of the entity","Align the requested unwrap type with the real identifier class (check persister.getIdentifierType().getReturnedClass())","For composite keys, bind the id-class object or each component separately","Update custom JavaType/JdbcType integrations to request the exact id class the entity declares"],"exampleFix":"// before\nnativeQuery.setParameter(\"owner\", ownerEntity); // binder unwraps to id class, mismatch -> throws\n\n// after\nnativeQuery.setParameter(\"owner\", ownerEntity.getId()); // bind the id itself","handlingStrategy":"type-guard","validationCode":"Class<?> idClass = session.getFactory().getMappingMetamodel()\n    .getEntityDescriptor(Owner.class)\n    .getIdentifierType().getReturnedClass();\nif (!idClass.isInstance(valueToBind)) {\n    throw new IllegalArgumentException(\"expected id type \" + idClass.getName());\n}","typeGuard":"static boolean idTypeMatches(SessionFactory sf, Class<?> entity, Object candidateId) {\n    Class<?> idClass = sf.getMappingMetamodel()\n        .getEntityDescriptor(entity).getIdentifierType().getReturnedClass();\n    return idClass.isInstance(candidateId);\n}","tryCatchPattern":"try {\n    query.setParameter(\"owner\", owner);\n} catch (IllegalArgumentException e) {\n    // unwrap/id mismatch: bind the identifier directly instead\n    query.setParameter(\"owner\", owner.getId());\n}","preventionTips":["Bind ids, not entity instances, to native queries","Keep one source of truth for id types across services","Smoke-test parameter binding after any @Id type change","Check persister.getIdentifierType().getReturnedClass() when writing generic binders"],"tags":["hibernate","orm","identifier","unwrap","entity"],"backgroundTag":"id-type-mismatch","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}