{"record":{"id":"6f3168cfaa171803","repo":"hibernate/hibernate-orm","slug":"argument-to-query-parameter-has-an-incompatible-ty-6f3168","errorCode":null,"errorMessage":"Argument to query parameter has an incompatible type: {}","messagePattern":"Argument to query parameter has an incompatible type: (.+?)","errorType":"exception","errorClass":"QueryArgumentException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/query/internal/QueryParameterBindingImpl.java","lineNumber":399,"sourceCode":"\n\tprivate void validate(Object value) {\n\t\tQueryParameterBindingValidator.validate( queryParameter, bindType, value, sessionFactory );\n\t}\n\n\tprivate Object coerce(Object value) {\n\t\ttry {\n\t\t\tif ( bindType != null ) {\n\t\t\t\treturn coerce( value, bindType );\n\t\t\t}\n//\t\t\telse if ( queryParameter.getHibernateType() != null ) {\n//\t\t\t\treturn coerce( value, queryParameter.getHibernateType() );\n//\t\t\t}\n\t\t\telse {\n\t\t\t\treturn value;\n\t\t\t}\n\t\t}\n\t\tcatch (HibernateException ex) {\n\t\t\tthrow new QueryArgumentException( \"Argument to query parameter has an incompatible type: \" + ex.getMessage(),\n\t\t\t\t\tqueryParameter.getParameterType(), value );\n\t\t}\n\t}\n\n\tprivate Object coerce(Object value, BindableType<T> parameterType) {\n\t\treturn value == null ? null\n\t\t\t\t: getCriteriaBuilder().resolveExpressible( parameterType )\n\t\t\t\t\t\t.getExpressibleJavaType().coerce( value );\n\t}\n\n\tprivate static <T> @Nullable T firstNonNull(Collection<? extends T> values) {\n\t\tfinal var iterator = values.iterator();\n\t\tT value = null;\n\t\twhile ( value == null && iterator.hasNext() ) {\n\t\t\tvalue = iterator.next();\n\t\t}\n\t\treturn value;\n\t}","sourceCodeStart":381,"sourceCodeEnd":417,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/query/internal/QueryParameterBindingImpl.java#L381-L417","documentation":"When a bound value must be converted to the parameter's bind type, QueryParameterBindingImpl.coerce applies the JavaType coercion; if that fails (a HibernateException, e.g. 'abc' to Integer), it is rethrown as QueryArgumentException with the parameter type and the offending value. It fires at binding time, so the stack trace points at the setParameter call, not at execution.","triggerScenarios":"setParameter(\"age\", \"abc\") where the parameter resolved to Integer; binding '31.12.2024' to a LocalDate parameter; any raw String from a web form or file forwarded into a typed parameter without conversion.","commonSituations":"REST controllers handing String request params straight to repositories; locale-specific or unexpected date formats; enum name mismatches; CSV/import pipelines feeding untyped data into queries.","solutions":["Convert the input to the parameter's Java type before binding (Integer.parseInt, LocalDate.parse with an explicit formatter).","Bind with an explicit matching BindableType when inference is ambiguous.","Validate and normalize external input at the API boundary so repositories only receive typed values."],"exampleFix":"// before\nq.setParameter(\"age\", request.getParameter(\"age\")); // \"abc\" -> QueryArgumentException\n\n// after\nint age = Integer.parseInt(request.getParameter(\"age\")); // validate at boundary\nq.setParameter(\"age\", age);","handlingStrategy":"validation","validationCode":"static Integer toInt(Object raw) {\n    if (raw instanceof Integer i) return i;\n    try {\n        return Integer.parseInt(String.valueOf(raw));\n    } catch (NumberFormatException e) {\n        throw new IllegalArgumentException(\"Not an integer: \" + raw, e);\n    }\n}","typeGuard":null,"tryCatchPattern":"try {\n    q.setParameter(\"age\", raw);\n} catch (org.hibernate.QueryArgumentException e) {\n    // message contains parameter type and value; reject the request input\n}","preventionTips":["Convert and validate web input at the API boundary before it reaches repositories.","Use explicit formatters for date/string parameters.","Bind typed values, never raw Strings, into typed query parameters."],"tags":["hibernate","parameter-binding","type-coercion","queryargumentexception","input-validation"],"backgroundTag":"query-argument-type-mismatch","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}