{"record":{"id":"52907c368d21aa5c","repo":"hibernate/hibernate-orm","slug":"the-sql-function-passes-an-argument-at-index-s-bu","errorCode":null,"errorMessage":"The SQL function passes an argument at index %s but the fragment contains no placeholder for the argument: %s","messagePattern":"The SQL function passes an argument at index (.+?) but the fragment contains no placeholder for the argument: (.+?)","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/dialect/function/SqlFunction.java","lineNumber":73,"sourceCode":"\t\t\t\tnull\n\t\t);\n\t}\n\n\t@Override\n\tpublic void render(\n\t\t\tSqlAppender sqlAppender,\n\t\t\tList<? extends SqlAstNode> arguments,\n\t\t\tReturnableType<?> returnType,\n\t\t\tSqlAstTranslator<?> walker) {\n\t\tfinal QueryLiteral<String> sqlFragmentLiteral = (QueryLiteral<String>) arguments.get( 0 );\n\t\tfinal String sqlFragment = sqlFragmentLiteral.getLiteralValue();\n\t\tif ( arguments.size() != 1 ) {\n\t\t\tint index = 0;\n\t\t\tfor ( int i = 1; i < arguments.size(); i++ ) {\n\t\t\t\tfinal SqlAstNode argument = arguments.get( i );\n\t\t\t\tfinal int paramIndex = sqlFragment.indexOf( '?', index );\n\t\t\t\tif ( paramIndex == -1 ) {\n\t\t\t\t\tthrow new IllegalArgumentException( \"The SQL function passes an argument at index \" + i\n\t\t\t\t\t\t\t+ \" but the fragment contains no placeholder for the argument: \" + sqlFragment );\n\t\t\t\t}\n\t\t\t\tsqlAppender.append( sqlFragment, index, paramIndex );\n\t\t\t\targument.accept( walker );\n\t\t\t\tindex = paramIndex + 1;\n\t\t\t}\n\t\t\tsqlAppender.append( sqlFragment, index, sqlFragment.length() );\n\t\t}\n\t\telse {\n\t\t\tsqlAppender.appendSql( sqlFragment );\n\t\t}\n\t}\n\n\t@Override\n\tpublic String getArgumentListSignature() {\n\t\treturn \"\";\n\t}\n}","sourceCodeStart":55,"sourceCodeEnd":91,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/dialect/function/SqlFunction.java#L55-L91","documentation":"HQL's sql(\"fragment\", args...) splices each extra argument into the fragment's next '?' placeholder, scanning left to right. When an argument arrives and no further '?' exists in the remaining fragment, rendering throws IllegalArgumentException naming the argument index and the full fragment.","triggerScenarios":"HQL: sql(\"coalesce(?, 0)\", e.a, e.b) — two extra arguments but only one placeholder; also '?' placeholders removed from a fragment while stale arguments remain.","commonSituations":"Dynamic SQL-fragment builders where fragment and argument list are assembled separately; editing template strings; forgetting that every '?' in the fragment (even inside quoted text) consumes one argument.","solutions":["Count the '?' placeholders in the fragment and the extra arguments — they must match one-to-one in order","Add the missing placeholder or remove the surplus argument","Beware '?' inside string literals of the fragment: they count as placeholders too"],"exampleFix":"// before\nselect sql(\"coalesce(?, 0)\", e.a, e.b) from Entity e\n\n// after\nselect sql(\"coalesce(?, ?)\", e.a, e.b) from Entity e   -- or sql(\"coalesce(?, 0)\", e.a)","handlingStrategy":"validation","validationCode":"// Every extra sql() argument needs exactly one '?' placeholder in the fragment\nstatic void checkSqlFragment(String fragment, int argCount) {\n    long placeholders = fragment.chars().filter(c -> c == '?').count();\n    if (placeholders != argCount) {\n        throw new IllegalArgumentException(\n            \"sql() fragment has \" + placeholders + \" placeholder(s) but \" + argCount + \" argument(s)\");\n    }\n}","typeGuard":null,"tryCatchPattern":"try {\n    return em.createQuery(hql).getResultList();\n} catch (IllegalArgumentException e) {\n    if (e.getMessage() != null && e.getMessage().contains(\"no placeholder\")) {\n        throw new QuerySetupException(\"Mismatch between sql() placeholders and arguments — check fragment template\", e);\n    }\n    throw e;\n}","preventionTips":["Build sql() calls from a template object that counts '?' and arguments together","Never edit the fragment string without recounting arguments","Remember '?' inside quoted text in the fragment still consumes an argument"],"tags":["hibernate","hql","sql-function","placeholder","template-mismatch"],"backgroundTag":"sql-template-placeholder-mismatch","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}