{"record":{"id":"9043b2431747daa8","repo":"hibernate/hibernate-orm","slug":"cannot-create-binding-for-parameter-reference","errorCode":null,"errorMessage":"Cannot create binding for parameter reference [{}] - reference is not a parameter of this query","messagePattern":"Cannot create binding for parameter reference \\[(.+?)\\] - reference is not a parameter of this query","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/query/internal/QueryParameterBindingsImpl.java","lineNumber":134,"sourceCode":"\tprivate static <T> QueryParameterBindingImpl<T> createBinding(\n\t\t\tSessionFactoryImplementor factory, QueryParameterBinding<T> binding) {\n\t\treturn new QueryParameterBindingImpl<>( binding.getQueryParameter(), factory, binding.getBindType() );\n\t}\n\n\tpublic QueryParameterBindingsImpl copyWithoutValues(SessionFactoryImplementor sessionFactory) {\n\t\treturn new QueryParameterBindingsImpl( this, sessionFactory );\n\t}\n\n\t@Override\n\tpublic boolean isBound(QueryParameterImplementor<?> parameter) {\n\t\treturn getBinding( parameter ).isBound();\n\t}\n\n\t@Override\n\tpublic <P> QueryParameterBinding<P> getBinding(QueryParameterImplementor<P> parameter) {\n\t\tfinal var binding = parameterBindingMap.get( parameter );\n\t\tif ( binding == null ) {\n\t\t\tthrow new IllegalArgumentException(\n\t\t\t\t\t\"Cannot create binding for parameter reference [\" + parameter + \"] - reference is not a parameter of this query\"\n\t\t\t);\n\t\t}\n\t\tif ( !binding.getQueryParameter().equals( parameter ) ) {\n\t\t\tthrow new IllegalStateException( \"Parameter binding corrupted for: \" + parameter.getName() );\n\t\t}\n\t\t@SuppressWarnings(\"unchecked\") // safe because we checked the parameter\n\t\tfinal var castBinding = (QueryParameterBinding<P>) binding;\n\t\treturn castBinding;\n\t}\n\n\t@Override\n\tpublic QueryParameterBinding<?> getBinding(int position) {\n\t\tfinal var binding = parameterBindingMapByNameOrPosition.get( position );\n\t\tif ( binding == null ) {\n\t\t\t// Invoke this method to throw the exception\n\t\t\tparameterMetadata.getQueryParameter( position );\n\t\t}","sourceCodeStart":116,"sourceCodeEnd":152,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/query/internal/QueryParameterBindingsImpl.java#L116-L152","documentation":"QueryParameterBindingsImpl.getBinding looks the passed QueryParameterImplementor up in this query's own parameterBindingMap. A reference that belongs to a different query (or to none) is not found, producing IllegalArgumentException 'reference is not a parameter of this query'. A found-but-unequal entry would instead indicate corrupted binding state (IllegalStateException), which is a different, internal failure.","triggerScenarios":"Calling query.setParameter(param, value) where param is a QueryParameter obtained from another query or session; frameworks or integrations that cache QueryParameter objects and replay them across queries. The internal path is reached whenever bindings are resolved for execution or flush.","commonSituations":"Storing QueryParameter references statically, in caches, or in long-lived DAO fields; mixing parameters of a named query with an ad-hoc query; custom listeners or wrappers that forward parameter objects between queries.","solutions":["Always obtain the parameter from the query being executed: query.getParameter(name) or query.getParameter(position).","Never cache or share QueryParameter instances across queries or sessions.","In shared/generic code, bind by name or position rather than by parameter reference."],"exampleFix":"// before\nQueryParameterImplementor<Integer> cached = otherQuery.getParameter(\"age\");\nthisQuery.setParameter(cached, 30); // throws: reference belongs to another query\n\n// after\nthisQuery.setParameter(\"age\", 30);","handlingStrategy":"validation","validationCode":"static boolean belongsTo(org.hibernate.query.Query<?> q, org.hibernate.query.QueryParameter<?> p) {\n    return q.getParameterMetadata().containsReference(p);\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Obtain parameter references from the query being executed, at bind time.","Never store QueryParameter objects in caches, statics, or long-lived fields.","Bind by name/position in generic code instead of passing references."],"tags":["hibernate","parameter-binding","query-parameter","internal-api"],"backgroundTag":"unknown-query-parameter","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}