{"record":{"id":"0ce640bcbe2221f6","repo":"hibernate/hibernate-orm","slug":"argument-to-query-parameter-has-an-incompatible-ty","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/AbstractCommonQueryContract.java","lineNumber":1415,"sourceCode":"\t\t\t@Nonnull Collection<? extends P> values,\n\t\t\t@Nonnull Type<P> type) {\n\t\tlocateBinding( name ).setBindValues( values, (BindableType<P>) type );\n\t\treturn this;\n\t}\n\n\t@Override\n\t@Nonnull\n\tpublic CommonQueryContractImplementor setParameterList(@Nonnull String name, @Nonnull Object[] values) {\n\t\tfinal var binding = getQueryParameterBindings().getBinding( name );\n\t\tsetParameterValues( values, binding );\n\t\treturn this;\n\t}\n\n\tprivate <P> void setParameterValues(Object[] values, QueryParameterBinding<P> binding) {\n\t\tfinal var parameterType = binding.getBindType();\n\t\tif ( parameterType != null\n\t\t\t&& !areInstances( parameterType, values, getNodeBuilder() ) ) {\n\t\t\tthrow new QueryArgumentException( \"Argument to query parameter has an incompatible type\",\n\t\t\t\t\tparameterType.getJavaType(), values.getClass().getComponentType(), values );\n\t\t}\n\t\t@SuppressWarnings(\"unchecked\") // safe, just checked\n\t\tfinal var castArray = (P[]) values;\n\t\tbinding.setBindValues( List.of( castArray ) );\n\t}\n\n\t@Override\n\t@Nonnull\n\tpublic <P> CommonQueryContractImplementor setParameterList(\n\t\t\t@Nonnull String name,\n\t\t\t@Nonnull P[] values,\n\t\t\t@Nonnull Class<P> javaType) {\n\t\tfinal var javaDescriptor = getJavaType( javaType );\n\t\tif ( javaDescriptor == null ) {\n\t\t\tsetParameterList( name, values );\n\t\t}\n\t\telse {","sourceCodeStart":1397,"sourceCodeEnd":1433,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/query/internal/AbstractCommonQueryContract.java#L1397-L1433","documentation":"Thrown (QueryArgumentException) by setParameterValues(Object[] values, QueryParameterBinding<P> binding), reached via setParameterList(String name, Object[] values): when the binding already knows its type (getBindType() != null) and QueryArguments.areInstances(parameterType, values, nodeBuilder) finds the array elements are not instances of that type, the bind is rejected before setBindValues. The exception carries the expected Java type, the array's component type, and the offending array.","triggerScenarios":"setParameterList(\"ids\", new String[]{\"1\",\"2\"}) where :ids was inferred as Long from 'o.id in :ids'. Passing Integer[] for a Long-typed parameter (Integer is not an instance of Long). Arrays of boxed values deserialized from JSON/web input (often String[]) forwarded straight into the bind.","commonSituations":"REST query-param lists arriving as String[] and bound without conversion; schema/type drift between entity attribute type and the frontend payload; refactoring entity id type from Integer to Long (or UUID) while callers still send the old array type.","solutions":["Convert the array to the parameter's exact component type first: Arrays.stream(strIds).map(Long::valueOf).toArray(Long[]::new)","Check the expected type via the parameter metadata and write the converter against it rather than hardcoding","For string-prone inputs, prefer setParameterList(name, List<Long>) after explicit conversion, or TypedParameterValue-free typed binds via setParameter(name, v, Long.class)"],"exampleFix":"// before\nquery.setParameterList( \"ids\", new String[]{ \"1\", \"2\" } ); // String[] into Long :ids\n\n// after\nLong[] ids = Arrays.stream( new String[]{ \"1\", \"2\" } ).map( Long::valueOf ).toArray( Long[]::new );\nquery.setParameterList( \"ids\", ids );","handlingStrategy":"validation","validationCode":"Class<?> expected = query.getParameterMetadata().getQueryParameter( name ).getParameterType();\nif ( !expected.isAssignableFrom( values.getClass().getComponentType() ) ) {\n    values = convert( values, expected ); // e.g. String[] -> Long[]\n}\nquery.setParameterList( name, values );","typeGuard":"static <T> boolean arrayMatchesParam(Class<T> expected, Object[] arr) {\n    return expected.isAssignableFrom( arr.getClass().getComponentType() );\n}","tryCatchPattern":"try {\n    query.setParameterList( name, values );\n} catch ( org.hibernate.query.QueryArgumentException e ) {\n    throw new IllegalArgumentException( \"IN parameter '\" + name + \"' needs \"\n            + e.getExpectedType() + \", got \" + (values == null ? \"null\" : values.getClass().getComponentType()), e );\n}","preventionTips":["Convert web/JSON string arrays to the entity id type before binding","Bind lists through setParameterList with the typed collection (List<Long>) rather than raw Object[]","When changing an id type in the schema, update every IN-list call site in the same change"],"tags":["hibernate","query-parameters","in-clause","type-mismatch","query-argument-exception"],"backgroundTag":"query-parameter-type-mismatch","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}