{"record":{"id":"cd7f12d3355fe2c2","repo":"hibernate/hibernate-orm","slug":"no-parameter-named-s-in-query-with-named-param","errorCode":null,"errorMessage":"No parameter named ':%s' in query with named parameters [%s]","messagePattern":"No parameter named ':(.+?)' in query with named parameters \\[(.+?)\\]","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/query/internal/ParameterMetadataImpl.java","lineNumber":268,"sourceCode":"\t@Override\n\tpublic QueryParameterImplementor<?> findQueryParameter(String name) {\n\t\treturn queryParametersByName == null ? null : queryParametersByName.get( name );\n\t}\n\n\t@Override\n\tpublic QueryParameterImplementor<?> getQueryParameter(String name) {\n\t\tfinal var parameter = findQueryParameter( name );\n\t\tif ( parameter != null ) {\n\t\t\treturn parameter;\n\t\t}\n\t\telse {\n\t\t\tfinal String errorMessage = String.format(\n\t\t\t\t\tLocale.ROOT,\n\t\t\t\t\t\"No parameter named ':%s' in query with named parameters [%s]\",\n\t\t\t\t\tname,\n\t\t\t\t\tString.join( \", \", getNamedParameterNames() )\n\t\t\t);\n\t\t\tthrow new IllegalArgumentException(\n\t\t\t\t\terrorMessage,\n\t\t\t\t\tnew UnknownParameterException( errorMessage )\n\t\t\t);\n\t\t}\n\t}\n\n\n\t// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\t// Positional parameter handling\n\n\t@Override\n\tpublic boolean hasPositionalParameters() {\n\t\treturn queryParametersByPosition != null && !queryParametersByPosition.isEmpty();\n\t}\n\n\tpublic Set<Integer> getOrdinalParameterLabels() {\n\t\treturn queryParametersByPosition == null ? emptySet() : queryParametersByPosition.keySet();\n\t}","sourceCodeStart":250,"sourceCodeEnd":286,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/query/internal/ParameterMetadataImpl.java#L250-L286","documentation":"ParameterMetadataImpl.getQueryParameter(String) looks a parameter up by name in queryParametersByName; when it is absent, Hibernate throws IllegalArgumentException (cause UnknownParameterException) and the message conveniently lists every named parameter the query actually declares. It fires from setParameter(name, ...) or getParameter(name) on a query that has no such :name token.","triggerScenarios":"Calling setParameter(\"status\", value) on a query whose HQL contains no :status placeholder; calling getParameter(\"x\") on a query that uses different parameter names or only ordinal ?N parameters.","commonSituations":"Typos between the HQL string and the binding call; refactoring a query string (renaming or removing a parameter) without updating bindings; dynamic query builders where a predicate is appended but its binding is missing or uses a stale name.","solutions":["Read the parameter list in the error message (or call query.getParameterMetadata().getNamedParameterNames()) and bind using one of those exact names.","Fix the typo on either side so the HQL token and the setParameter name match.","In dynamic query builders, add the predicate and its binding in the same conditional block so names cannot drift."],"exampleFix":"// before\nvar q = session.createQuery(\"from Person p where p.status = :stat\", Person.class);\nq.setParameter(\"status\", \"ACTIVE\"); // throws: no parameter named ':status'\n\n// after\nq.setParameter(\"stat\", \"ACTIVE\"); // matches :stat in the HQL","handlingStrategy":"validation","validationCode":"static void requireNamedParam(org.hibernate.query.Query<?> q, String name) {\n    if (!q.getParameterMetadata().getNamedParameterNames().contains(name))\n        throw new IllegalArgumentException(\"Query declares no parameter :\" + name\n            + \" - declared: \" + q.getParameterMetadata().getNamedParameterNames());\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Derive binding names from a single constants class shared with the HQL strings.","In dynamic builders, append predicate and binding together in one method.","Write a smoke test per repository method that executes each query with dummy bindings."],"tags":["hibernate","hql","named-parameters","parameter-binding","typo"],"backgroundTag":"unknown-query-parameter","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}