{"record":{"id":"e47d96292702f4f3","repo":"hibernate/hibernate-orm","slug":"given-type-is-incompatible-with-parameter-type","errorCode":null,"errorMessage":"Given type is incompatible with parameter type","messagePattern":"Given type is incompatible with parameter type","errorType":"exception","errorClass":"QueryArgumentException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/query/internal/QueryParameterBindingImpl.java","lineNumber":347,"sourceCode":"\t}\n\n\tprivate <V> void clarifyType(Object valueOrValues, BindableType<V> clarifiedType) {\n\t\tif ( clarifiedType != null ) {\n\t\t\tcheckClarifiedType( clarifiedType, valueOrValues );\n\t\t\t@SuppressWarnings(\"unchecked\") // safe\n\t\t\tfinal var newType = (BindableType<T>) clarifiedType;\n\t\t\tbindType = newType;\n\t\t}\n\t}\n\n\tprivate <A> void checkClarifiedType(\n\t\t\t@Nonnull BindableType<A> clarifiedType,\n\t\t\tObject valueOrValues) {\n\t\tfinal var parameterType = queryParameter.getParameterType();\n\t\tif ( parameterType != null ) {\n\t\t\tfinal var clarifiedJavaType = clarifiedType.getJavaType();\n\t\t\tif ( !parameterType.isAssignableFrom( clarifiedJavaType ) ) {\n\t\t\t\tthrow new QueryArgumentException(\n\t\t\t\t\t\t\"Given type is incompatible with parameter type\",\n\t\t\t\t\t\tparameterType, clarifiedJavaType, valueOrValues\n\t\t\t\t);\n\t\t\t}\n\t\t}\n\t\telse {\n\t\t\tassert queryParameter.getHibernateType() == null;\n\t\t}\n\t}\n\n\tprivate T cast(Object value) {\n\t\tif ( value == null ) {\n\t\t\treturn null;\n\t\t}\n\t\telse {\n\t\t\tfinal var bindableType =\n\t\t\t\t\tgetCriteriaBuilder()\n\t\t\t\t\t\t\t.resolveExpressible( bindType );","sourceCodeStart":329,"sourceCodeEnd":365,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/query/internal/QueryParameterBindingImpl.java#L329-L365","documentation":"When a parameter is bound with an explicit BindableType (a typed setParameter overload or setParameter with a Class/type argument), checkClarifiedType verifies that the given Java type is assignable to the parameter's resolved type. A mismatch throws QueryArgumentException carrying the parameter type, the supplied type, and the value, so the offending argument is identifiable from the message.","triggerScenarios":"setParameter(\"age\", 30, String.class) on a parameter Hibernate resolved as Integer; giving LocalDate.class for a LocalDateTime parameter; any typed overload whose Class does not match the parameter type inferred from the HQL expression.","commonSituations":"Copy-pasted typed bindings after an entity attribute changed type; enum vs String hints; migrating from Hibernate 5 where explicit type hints were more forgiving.","solutions":["Make the explicit type match the parameter's declared/inferred type, or drop the hint and let Hibernate infer from the bound value.","Check the parameter type first: query.getParameterMetadata().getQueryParameter(name).getParameterType().","After changing an entity attribute type, grep for typed setParameter calls that mention the old Class."],"exampleFix":"// before\nvar q = session.createQuery(\"from Person p where p.name = :name\", Person.class);\nq.setParameter(\"name\", \"Alice\", Integer.class); // Integer not assignable to String\n\n// after\nq.setParameter(\"name\", \"Alice\"); // let Hibernate infer","handlingStrategy":"type-guard","validationCode":"static boolean typeCompatible(org.hibernate.query.Query<?> q, String name, Class<?> javaType) {\n    Class<?> parameterType = q.getParameterMetadata().getQueryParameter(name).getParameterType();\n    return parameterType == null || parameterType.isAssignableFrom(javaType);\n}","typeGuard":"static boolean typeCompatible(org.hibernate.query.Query<?> q, String name, Class<?> javaType) {\n    Class<?> parameterType = q.getParameterMetadata().getQueryParameter(name).getParameterType();\n    return parameterType == null || parameterType.isAssignableFrom(javaType);\n}","tryCatchPattern":null,"preventionTips":["Omit explicit type hints unless inference fails; let Hibernate resolve from the value.","After changing an attribute type, grep for typed setParameter calls naming the old Class.","Centralize typed bindings per parameter in one helper."],"tags":["hibernate","parameter-binding","type-mismatch","queryargumentexception"],"backgroundTag":"query-argument-type-mismatch","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}