{"record":{"id":"147b4602e6ca9ce4","repo":"hibernate/hibernate-orm","slug":"unknown-placeholder-token","errorCode":null,"errorMessage":"Unknown placeholder {token}","messagePattern":"Unknown placeholder (.+?)","errorType":"exception","errorClass":"QueryException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/query/sql/internal/SQLQueryParser.java","lineNumber":215,"sourceCode":"\t\t\t\tif ( defaultSchema != null ) {\n\t\t\t\t\tresult.append( defaultSchema.render(dialect) );\n\t\t\t\t\tresult.append( \".\" );\n\t\t\t\t}\n\t\t\t\tbreak;\n\t\t\tcase \"h-schema\":\n\t\t\t\tif ( defaultSchema != null ) {\n\t\t\t\t\tresult.append( defaultSchema.render(dialect) );\n\t\t\t\t\tresult.append( \".\" );\n\t\t\t\t}\n\t\t\t\tbreak;\n\t\t\tcase \"h-catalog\":\n\t\t\t\tif ( defaultCatalog != null ) {\n\t\t\t\t\tresult.append( defaultCatalog.render(dialect) );\n\t\t\t\t\tresult.append( \".\" );\n\t\t\t\t}\n\t\t\t\tbreak;\n\t\t\tdefault:\n\t\t\t\tthrow new QueryException( \"Unknown placeholder \", token);\n\t\t}\n\t}\n\n\tprivate String resolveCollectionProperties(String aliasName, String propertyName, String token) {\n\t\tfinal var fieldResults = context.getPropertyResultsMap( aliasName );\n\t\tfinal var collectionPersister = context.getCollectionPersister( aliasName );\n\t\tfinal String collectionSuffix = context.getCollectionSuffix( aliasName );\n\t\tswitch ( propertyName ) {\n\t\t\tcase \"*\":\n\t\t\t\tif ( !fieldResults.isEmpty() ) {\n\t\t\t\t\tthrow new QueryException(\n\t\t\t\t\t\t\t\"Illegal interpolation '%s' ('%s' is a field alias)\"\n\t\t\t\t\t\t\t\t\t.formatted( token, aliasName ),\n\t\t\t\t\t\t\toriginalQueryString\n\t\t\t\t\t);\n\t\t\t\t}\n\t\t\t\taliasesFound++;\n\t\t\t\treturn collectionPersister.selectFragment( aliasName, collectionSuffix )","sourceCodeStart":197,"sourceCodeEnd":233,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/query/sql/internal/SQLQueryParser.java#L197-L233","documentation":"Legacy native queries support '{...}' interpolation. SQLQueryParser recognizes only built-in keywords {h-schema} and {h-catalog} plus alias-bound tokens like {alias.prop} and {alias.*} resolved against declared returns. Any other token between braces reaches the default branch and throws QueryException(\"Unknown placeholder\", token).","triggerScenarios":"Native SQL containing e.g. {schema}, {catalog}, {tenant}, or a mistyped {h-schame}, none of which are keywords or declared return aliases. Fires when the query string is parsed/expanded, i.e. when the query is prepared for execution.","commonSituations":"Teams assuming arbitrary template variables are supported inside braces; typos in {h-schema}; custom placeholder syntax from in-house query templates leaking into Hibernate-managed native queries; migration from very old Hibernate where extra placeholders were interpolated by hand.","solutions":["Use the supported built-ins: {h-schema} renders the default schema (append '.'), {h-catalog} the default catalog.","Remove the braces and inline the value yourself, or keep templating outside Hibernate and pass the finished SQL string in.","If the token was meant to be an alias interpolation, declare the alias (addEntity/addScalar/addJoin) with that exact name or fix the typo."],"exampleFix":"-- before\nselect * from {schema}users where ...\n\n-- after\nselect * from {h-schema}users where ...","handlingStrategy":"validation","validationCode":"static final java.util.Set<String> BUILTIN_PLACEHOLDERS = java.util.Set.of(\"h-schema\", \"h-catalog\");\nstatic void validatePlaceholders(String sql, java.util.Set<String> declaredAliases) {\n    var m = java.util.regex.Pattern.compile(\"\\\\{([A-Za-z_][\\\\w-]*)(?:[.*]|\\\\})\").matcher(sql);\n    while (m.find()) {\n        String head = m.group(1);\n        if (!BUILTIN_PLACEHOLDERS.contains(head) && !declaredAliases.contains(head))\n            throw new IllegalArgumentException(\"Unknown placeholder {\" + head + \"} in native query\");\n    }\n}","typeGuard":null,"tryCatchPattern":"try { query.list(); } catch (org.hibernate.QueryException e) { /* if 'Unknown placeholder', replace {token} with {h-schema}/{h-catalog} or the declared alias form */ throw e; }","preventionTips":["Document the only legal braces content: {h-schema}, {h-catalog}, {alias.prop}, {alias.*}.","Do your own templating before handing SQL to Hibernate so braces never carry custom variables."],"tags":["hibernate","native-query","placeholder","interpolation","query-exception"],"backgroundTag":"unknown-placeholder-in-native-query","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}