{"record":{"id":"70ea12cb226809a7","repo":"hibernate/hibernate-orm","slug":"cannot-cast-to-entity-type","errorCode":null,"errorMessage":"Cannot cast to entity type '{}'","messagePattern":"Cannot cast to entity type '(.+?)'","errorType":"exception","errorClass":"ClassCastException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/query/internal/QueryArguments.java","lineNumber":119,"sourceCode":"\n\tpublic static <T> T cast(Object value, JavaType<T> javaType) {\n\t\tif ( value == null ) {\n\t\t\treturn null;\n\t\t}\n\t\telse if ( javaType instanceof EntityJavaType<?> ) {\n\t\t\t// special handling for entity arguments due to\n\t\t\t// the possibility of an uninitialized proxy\n\t\t\t// (which we don't want or need to fetch)\n\t\t\tif ( isInstance( value, javaType ) ) {\n\t\t\t\t// The proxy might not literally be an\n\t\t\t\t// instance of the entity class represented\n\t\t\t\t// by the unreified type T, but it is an\n\t\t\t\t// instance in spirit\n\t\t\t\t//noinspection unchecked\n\t\t\t\treturn (T) value;\n\t\t\t}\n\t\t\telse {\n\t\t\t\tthrow new ClassCastException( \"Cannot cast to entity type '\"\n\t\t\t\t\t\t\t+ javaType.getJavaTypeClass().getTypeName() + \"'\" );\n\t\t\t}\n\t\t}\n\t\telse {\n\t\t\t// require that the argument be assignable to the parameter\n\t\t\treturn javaType.cast( javaType.coerce( value ) );\n\t\t}\n\t}\n}\n","sourceCodeStart":101,"sourceCodeEnd":129,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/query/internal/QueryArguments.java#L101-L129","documentation":"When a query argument is bound against an entity-typed parameter, QueryArguments special-cases Hibernate proxies (isInstance) but otherwise requires the value to be an instance of the entity's Java class. A value of any other class produces ClassCastException with the message 'Cannot cast to entity type <FQCN>'. This is Hibernate's entity-argument conversion path, not a bad cast in user code.","triggerScenarios":"setParameter(\"c\", value) on a query like \"from Order o where o.customer = :c\" where value is an instance of a different entity class (e.g. Vendor instead of Customer), or a DTO/Map passed where the mapped entity is expected.","commonSituations":"Similar domain classes or inheritance hierarchies where the wrong subtype flows through generic code; values arriving from generic Map<String,Object> request contexts; refactors that changed an entity type while callers still pass the old one.","solutions":["Pass an instance of the exact entity class the comparison expects.","Compare by identifier instead: 'where o.customer.id = :cid' and bind customer.getId().","When types are uncertain, inspect query.getParameterMetadata().getQueryParameter(name).getParameterType() before binding."],"exampleFix":"// before\nvar q = session.createQuery(\"from Order o where o.customer = :c\", Order.class);\nq.setParameter(\"c\", someVendor); // Vendor is not Customer -> ClassCastException\n\n// after\nq.setParameter(\"c\", customer);\n// or compare by id:\nvar q2 = session.createQuery(\"from Order o where o.customer.id = :cid\", Order.class);\nq2.setParameter(\"cid\", customer.getId());","handlingStrategy":"type-guard","validationCode":"static void bindEntity(org.hibernate.query.Query<?> q, String name, Object value, Class<?> entityJavaType) {\n    Object unwrapped = org.hibernate.Hibernate.unproxy(value);\n    if (unwrapped != null && !entityJavaType.isInstance(unwrapped))\n        throw new IllegalArgumentException(\"Expected \" + entityJavaType.getSimpleName()\n            + \" but got \" + unwrapped.getClass().getSimpleName());\n    q.setParameter(name, value);\n}","typeGuard":"static boolean isEntityInstance(Object value, Class<?> entityJavaType) {\n    return value == null || entityJavaType.isInstance(org.hibernate.Hibernate.unproxy(value));\n}","tryCatchPattern":null,"preventionTips":["Compare by foreign key id instead of entity instance where possible.","Avoid passing entities through generic Map<String,Object> contexts.","Type the repository layer so the compiler catches entity mix-ups."],"tags":["hibernate","classcastexception","entity-parameter","type-mismatch","proxy"],"backgroundTag":"query-argument-type-mismatch","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}