{"record":{"id":"9f0a17804644f579","repo":"hibernate/hibernate-orm","slug":"argument-could-not-be-converted-to-the-identi","errorCode":null,"errorMessage":"Argument '{}' could not be converted to the identifier type of entity '{}' [{}]","messagePattern":"Argument '(.+?)' could not be converted to the identifier type of entity '(.+?)' \\[(.+?)\\]","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/loader/internal/IdentifierLoadAccessImpl.java","lineNumber":204,"sourceCode":"\t\tinitializeIfNecessary( result );\n\t\t//noinspection unchecked\n\t\treturn (T) result;\n\t}\n\n\t// Used by Hibernate Reactive\n\tprotected Object coerceId(Object id, SessionFactoryImplementor factory) {\n\t\tif ( isLoadByIdComplianceEnabled( factory ) ) {\n\t\t\treturn id;\n\t\t}\n\t\telse {\n\t\t\ttry {\n\t\t\t\tfinal var identifierMapping = entityPersister.getIdentifierMapping();\n\t\t\t\treturn identifierMapping.isVirtual()\n\t\t\t\t\t\t? id // special case for a class with an @IdClass\n\t\t\t\t\t\t: identifierMapping.getJavaType().coerce( id );\n\t\t\t}\n\t\t\tcatch ( Exception e ) {\n\t\t\t\tthrow new IllegalArgumentException( \"Argument '\" + id\n\t\t\t\t\t\t+ \"' could not be converted to the identifier type of entity '\"\n\t\t\t\t\t\t+ entityPersister.getEntityName() + \"'\"\n\t\t\t\t\t\t+ \" [\" + e.getMessage() + \"]\", e );\n\t\t\t}\n\t\t}\n\t}\n\n\tprivate void initializeIfNecessary(Object result) {\n\t\tif ( result != null ) {\n\t\t\tfinal var lazyInitializer = extractLazyInitializer( result );\n\t\t\tif ( lazyInitializer != null ) {\n\t\t\t\tif ( lazyInitializer.isUninitialized() ) {\n\t\t\t\t\tlazyInitializer.initialize();\n\t\t\t\t}\n\t\t\t}\n\t\t\telse {\n\t\t\t\tfinal var enhancementMetadata = entityPersister.getBytecodeEnhancementMetadata();\n\t\t\t\tif ( enhancementMetadata.isEnhancedForLazyLoading()","sourceCodeStart":186,"sourceCodeEnd":222,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/loader/internal/IdentifierLoadAccessImpl.java#L186-L222","documentation":"coerceId(...) on IdentifierLoadAccessImpl converts the argument of byId(...).load/getReference/reference into the entity's declared identifier JavaType via JavaType.coerce before hitting the database. If the runtime type cannot be converted, the coercion exception is wrapped in an IllegalArgumentException that names the entity and embeds the cause message.","triggerScenarios":"session.byId(User.class).getReference(\"1\") or .load(...) where the id field is Long; passing a String to a UUID-typed identifier; with hibernate.jpa.compliance.load_by_id=true coercion is skipped entirely (that flag off, the default, is what performs coercion and can raise this); @IdClass virtual id mappings bypass coercion.","commonSituations":"Web-layer path variables and request parameters arriving as String while the entity key is Long or UUID; changing the identifier type during a schema migration; turning on JPA compliance flags and changing where type mismatches surface.","solutions":["Convert the id to the entity's declared identifier type before calling load: Long.valueOf(value) or UUID.fromString(value).","Verify hibernate.jpa.compliance.load_by_id is set as intended (false by default enables the lenient coercion this error comes from).","Centralize id parsing in a helper (e.g., toEntityId(String)) instead of relying on Hibernate coercion."],"exampleFix":"// before: String argument for a Long id\nUser u = session.byId(User.class).load(\"1\");\n\n// after\nUser u = session.byId(User.class).load(Long.valueOf(\"1\"));","handlingStrategy":"type-guard","validationCode":null,"typeGuard":"static boolean idMatches( SessionFactory sf, Class<?> entity, Object id ) {\n    Class<?> idClass = sf.getMetamodel().entity( entity ).getId( Object.class ).getJavaType();\n    return idClass.isInstance( id );\n}","tryCatchPattern":"try {\n    return session.byId( User.class ).load( idArg );\n}\ncatch ( IllegalArgumentException e ) {\n    // message starts with: Argument '<id>' could not be converted\n    throw new BadEntityIdException( idArg, e );\n}","preventionTips":["Type controller and service parameters as the entity id class (Long/UUID), not String","Validate and convert ids at the API boundary before they reach persistence","Encapsulate id creation in factory methods so mismatched types cannot propagate"],"tags":["hibernate","identifier","type-coercion","jpa-compliance"],"backgroundTag":"id-type-mismatch","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}