{"record":{"id":"ba76f36111384839","repo":"hibernate/hibernate-orm","slug":"criteria-parameter-not-known-to-be-a-paramete","errorCode":null,"errorMessage":"Criteria parameter [{}] not known to be a parameter of the processing tree","messagePattern":"Criteria parameter \\[(.+?)\\] not known to be a parameter of the processing tree","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/query/sqm/sql/spi/BaseSqmToSqlAstConverter.java","lineNumber":6838,"sourceCode":"\n\tprivate SqmParameter<?> getSqmParameter(SqmExpression<?> parameter) {\n\t\tif ( parameter instanceof JpaCriteriaParameter<?> ) {\n\t\t\treturn getSqmParameter( (JpaCriteriaParameter<?>) parameter );\n\t\t}\n\t\telse if ( parameter instanceof SqmParameter<?> ) {\n\t\t\treturn (SqmParameter<?>) parameter;\n\t\t}\n\t\treturn null;\n\t}\n\n\tprivate SqmParameter<?> getSqmParameter(JpaCriteriaParameter<?> expression) {\n\t\tif ( jpaCriteriaParamResolutions == null ) {\n\t\t\tthrow new IllegalStateException( \"No JpaCriteriaParameter resolutions registered\" );\n\t\t}\n\n\t\tfinal var supplier = jpaCriteriaParamResolutions.get( expression );\n\t\tif ( supplier == null ) {\n\t\t\tthrow new IllegalStateException( \"Criteria parameter [\" + expression + \"] not known to be a parameter of the processing tree\" );\n\t\t}\n\t\treturn supplier;\n\t}\n\n\t@Override\n\tpublic Object visitTuple(SqmTuple<?> sqmTuple) {\n\t\tfinal var groupedExpressions = sqmTuple.getGroupedExpressions();\n\t\tfinal int size = groupedExpressions.size();\n\t\tfinal List<Expression> expressions = new ArrayList<>( size );\n\t\tif ( resolveInferredType() instanceof ValueMapping valueMapping\n\t\t\t\t&& valueMapping.getMappedType() instanceof EmbeddableMappingType embeddableMappingType ) {\n\t\t\tfor ( int i = 0; i < size; i++ ) {\n\t\t\t\tfinal var attributeMapping = embeddableMappingType.getAttributeMapping( i );\n\t\t\t\tinferrableTypeAccessStack.push( () -> attributeMapping );\n\t\t\t\ttry {\n\t\t\t\t\texpressions.add( (Expression) groupedExpressions.get( i ).accept( this ) );\n\t\t\t\t}\n\t\t\t\tfinally {","sourceCodeStart":6820,"sourceCodeEnd":6856,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/query/sqm/sql/spi/BaseSqmToSqlAstConverter.java#L6820-L6856","documentation":"getSqmParameter(JpaCriteriaParameter) looks the parameter up in jpaCriteriaParamResolutions, the map Hibernate builds when it first walks the criteria query tree. A missing entry means this JpaCriteriaParameter object was not present in the tree at compilation time - typically because the parameter was created for another query, or the tree was changed after the typed query was built.","triggerScenarios":"Binding a ParameterExpression that belongs to a different criteria query instance; copying criteria fragments (predicates holding parameters) between queries; modifying the criteria tree after calling createQuery and then binding; reusing static ParameterExpression fields across many queries built from different CriteriaBuilder instances.","commonSituations":"Shared predicate libraries and static parameter constants; query DTOs that cache criteria pieces; Spring Data JPA custom repository fragments; code migrated from EclipseLink where cross-query parameter reuse happened to work.","solutions":["Create parameters fresh inside each query and bind with the exact same object","Call createQuery(...) again after any mutation of the criteria tree, then bind parameters","Prefer named parameters (setParameter(\"name\", value)) over passing the ParameterExpression object","Make shared predicate factories take the query's criteria builder and create parameters per call"],"exampleFix":"// before (static shared parameter)\nprivate static final ParameterExpression<Long> ID = ...;\nQuery q1 = session.createQuery(cq1); q1.setParameter(ID, 1L);\n\n// after (per-query parameter)\nParameterExpression<Long> id = cb.parameter(Long.class);\ncq.where(cb.equal(root.get(\"id\"), id));\nQuery q1 = session.createQuery(cq1); q1.setParameter(id, 1L);","handlingStrategy":"validation","validationCode":"// Before binding, confirm the parameter belongs to this query\nif (!query.getParameters().contains(theParameter)) {\n    throw new IllegalStateException(\"Parameter does not belong to this query; create it with this query's CriteriaBuilder\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    query.setParameter(theParam, value);\n} catch (IllegalStateException e) {\n    if (e.getMessage() != null && e.getMessage().contains(\"not known to be a parameter\")) {\n        // rebuild from criteria and rebind\n        Query<?> fresh = session.createQuery(cq);\n        fresh.setParameter(theParam, value);\n        return fresh.getResultList();\n    }\n    throw e;\n}","preventionTips":["Never share ParameterExpression instances across queries","Re-run createQuery after mutating a criteria tree before binding","Prefer named parameters for stable binding across query rebuilds"],"tags":["hibernate","criteria","query-parameter","illegal-state"],"backgroundTag":"criteria-parameter-not-registered","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}