{"record":{"id":"eb8d9c1cf91ad18f","repo":"hibernate/hibernate-orm","slug":"could-not-resolve-jakarta-persistence-parameter","errorCode":null,"errorMessage":"Could not resolve jakarta.persistence.Parameter '{}' to org.hibernate.query.QueryParameter","messagePattern":"Could not resolve jakarta\\.persistence\\.Parameter '(.+?)' to org\\.hibernate\\.query\\.QueryParameter","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/query/internal/ParameterMetadataImpl.java","lineNumber":230,"sourceCode":"\tpublic boolean hasAnyMatching(Predicate<QueryParameterImplementor<?>> filter) {\n\t\tfor ( var queryParameter : queryParameters.keySet() ) {\n\t\t\tif ( filter.test( queryParameter ) ) {\n\t\t\t\treturn true;\n\t\t\t}\n\t\t}\n\n\t\treturn false;\n\t}\n\n\t@Override\n\tpublic <P> QueryParameterImplementor<P> resolve(Parameter<P> param) {\n\t\tif ( param instanceof QueryParameterImplementor<P> parameterImplementor ) {\n\t\t\treturn parameterImplementor;\n\t\t}\n\n\t\tfinal String errorMessage =\n\t\t\t\t\"Could not resolve jakarta.persistence.Parameter '\" + param + \"' to org.hibernate.query.QueryParameter\";\n\t\tthrow new IllegalArgumentException(\n\t\t\t\terrorMessage,\n\t\t\t\tnew UnknownParameterException( errorMessage )\n\t\t);\n\t}\n\n\n\t// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\t// Named parameter handling\n\n\t@Override\n\tpublic boolean hasNamedParameters() {\n\t\treturn queryParametersByName != null && !queryParametersByName.isEmpty();\n\t}\n\n\t@Override\n\tpublic Set<String> getNamedParameterNames() {\n\t\treturn queryParametersByName == null ? emptySet() : queryParametersByName.keySet();\n\t}","sourceCodeStart":212,"sourceCodeEnd":248,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/query/internal/ParameterMetadataImpl.java#L212-L248","documentation":"ParameterMetadataImpl.resolve(jakarta.persistence.Parameter) only accepts parameters that are Hibernate QueryParameterImplementor instances belonging to this query's own metadata. Any other jakarta.persistence.Parameter (from a different query, a different provider integration, or a criteria parameter not used to build this query) cannot be mapped, so it throws IllegalArgumentException with an UnknownParameterException cause.","triggerScenarios":"Calling query.setParameter(param, value) where param was obtained from a different query object (another createQuery call), or passing a CriteriaBuilder ParameterExpression that was not part of building this particular query. Internally, ParameterMetadata.resolve() is the throwing path.","commonSituations":"Generic repository layers that cache Parameter objects statically or in request scope; reusing one ParameterExpression across several criteria queries; code ported from environments where Parameter references were shared freely.","solutions":["Bind by name or position instead: setParameter(\"status\", value) or setParameter(1, value).","Fetch the Parameter from the same query you execute: query.getParameter(\"status\").","For criteria queries, bind through the same CriteriaQuery instance the ParameterExpression was used in."],"exampleFix":"// before\nParameter<?> param = otherQuery.getParameter(\"status\");\nthisQuery.setParameter(param, \"ACTIVE\"); // throws: not a parameter of this query\n\n// after\nthisQuery.setParameter(\"status\", \"ACTIVE\");\n// or\nthisQuery.setParameter(thisQuery.getParameter(\"status\"), \"ACTIVE\");","handlingStrategy":"validation","validationCode":"static boolean isParameterOf(jakarta.persistence.Query q, jakarta.persistence.Parameter<?> p) {\n    return q.getParameters().contains(p);\n}","typeGuard":"static boolean isHibernateQueryParameter(jakarta.persistence.Parameter<?> p) {\n    return p instanceof org.hibernate.query.QueryParameter;\n}","tryCatchPattern":null,"preventionTips":["Bind by name or position in shared code instead of passing Parameter objects around.","Obtain Parameter references from the same query you will execute.","Never cache Parameter objects statically or across sessions."],"tags":["hibernate","jpa","parameter-binding","query-parameter","illegal-argument"],"backgroundTag":"unknown-query-parameter","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}