{"record":{"id":"aa296a710f94b5c2","repo":"hibernate/hibernate-orm","slug":"json-path-jsonpath-uses-parameter-parametern-aa296a","errorCode":null,"errorMessage":"JSON path [{jsonPath}] uses parameter [{parameterName}] that is not passed","messagePattern":"JSON path \\[(.+?)\\] uses parameter \\[(.+?)\\] that is not passed","errorType":"exception","errorClass":"QueryException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/dialect/function/json/JsonPathHelper.java","lineNumber":115,"sourceCode":"\t\tsqlAppender.append( '\\'' );\n\t\tsqlAppender.append( prefix );\n\t\tfinal int start;\n\t\tif ( parts[0].isEmpty() ) {\n\t\t\tstart = 2;\n\t\t\tsqlAppender.append( '$' );\n\t\t\tsqlAppender.append( parts[1] );\n\t\t}\n\t\telse {\n\t\t\tstart = 0;\n\t\t}\n\t\tfor ( int i = start; i < parts.length; i++ ) {\n\t\t\tfinal String part = parts[i];\n\n\t\t\tfinal int parameterNameEndIndex = indexOfNonIdentifier( part, 0 );\n\t\t\tfinal String parameterName = part.substring( 0, parameterNameEndIndex );\n\t\t\tfinal Expression expression = passingClause.getPassingExpressions().get( parameterName );\n\t\t\tif ( expression == null ) {\n\t\t\t\tthrow new QueryException( \"JSON path [\" + jsonPath + \"] uses parameter [\" + parameterName + \"] that is not passed\" );\n\t\t\t}\n\t\t\tfinal Object literalValue = walker.getLiteralValue( expression );\n\t\t\tif ( literalValue instanceof String string ) {\n\t\t\t\tappendLiteral( sqlAppender, 0, string );\n\t\t\t}\n\t\t\telse {\n\t\t\t\tsqlAppender.appendSql( String.valueOf( literalValue ) );\n\t\t\t}\n\t\t\tappendLiteral( sqlAppender, parameterNameEndIndex, part );\n\t\t}\n\t\tsqlAppender.appendSql( '\\'' );\n\t}\n\n\tprivate static void appendLiteral(SqlAppender sqlAppender, int parameterNameEndIndex, String part) {\n\t\tfor ( int j = parameterNameEndIndex; j < part.length(); j++ ) {\n\t\t\tfinal char c = part.charAt( j );\n\t\t\tif ( c == '\\'') {\n\t\t\t\tsqlAppender.appendSql( '\\'' );","sourceCodeStart":97,"sourceCodeEnd":133,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/dialect/function/json/JsonPathHelper.java#L97-L133","documentation":"When a dialect inlines the passing clause into a single concatenated path literal, each $name reference must resolve to an expression in the passing clause. The helper splits the path, extracts the identifier, and looks it up in passingClause.getPassingExpressions(). A missing name throws this QueryException.","triggerScenarios":"A json_value or json_query query on an emulating dialect (for example H2) uses a path with [$name] or $name but the PASSING clause does not bind that exact name.","commonSituations":"Alias typos between the path and the AS alias. Paths assembled at runtime from templates that reference parameters the query never declared.","solutions":["Add the missing binding with an exact alias match: PASSING :i AS name.","Verify the identifier characters: the parser reads the name only up to the first non-identifier character.","Replace the parameter reference with a literal index or literal attribute.","Add a startup check that compares $names in the path with the passing aliases you bind."],"exampleFix":"// before\nselect json_value(e.doc, '$.items[$idx]') from Entity e\n\n// after\nselect json_value(e.doc, '$.items[$idx]' passing :i as idx) from Entity e","handlingStrategy":"validation","validationCode":"static void checkPassingBindings(String path, Map<String, Object> bindings) {\n    var m = java.util.regex.Pattern.compile(\"\\\\$(\\\\w+)\").matcher(path);\n    while (m.find()) {\n        if (!bindings.containsKey(m.group(1))) {\n            throw new IllegalArgumentException(\"JSON path references unbound parameter $\" + m.group(1));\n        }\n    }\n}","typeGuard":null,"tryCatchPattern":"try {\n    return session.createQuery(hql, String.class).getSingleResult();\n} catch (org.hibernate.QueryException e) {\n    if (e.getMessage() != null && e.getMessage().contains(\"that is not passed\")) {\n        throw new IllegalArgumentException(\"Add the missing PASSING binding: \" + e.getMessage(), e);\n    }\n    throw e;\n}","preventionTips":["Bind every $name that appears in a path before you run the query.","Keep path templates and their alias maps in one configuration unit.","Add a unit test per query template that checks path names against bindings."],"tags":["hibernate","json","json-path","passing-clause","parameter-mismatch"],"backgroundTag":"json-path-parameter-not-passed","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}