{"record":{"id":"220cb50b6e8f9293","repo":"hibernate/hibernate-orm","slug":"parameter-value-not-yet-bound-param","errorCode":null,"errorMessage":"Parameter value not yet bound : {param}","messagePattern":"Parameter value not yet bound : (.+?)","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/query/internal/AbstractCommonQueryContract.java","lineNumber":937,"sourceCode":"\t\t\treturn castParameter;\n\t\t}\n\t\tcatch ( HibernateException e ) {\n\t\t\tthrow getExceptionConverter().convert( e );\n\t\t}\n\t}\n\n\t@Override\n\tpublic <T> T getParameterValue(@Nonnull Parameter<T> param) {\n\t\tsession.checkOpen( false );\n\t\tfinal var parameter = getParameterMetadata().resolve( param );\n\t\tif ( parameter == null ) {\n\t\t\tthrow new IllegalArgumentException( \"The parameter [\" + param + \"] is not part of this Query\" );\n\t\t}\n\t\tfinal var binding =\n\t\t\t\tgetQueryParameterBindings()\n\t\t\t\t\t\t.getBinding( getQueryParameter( parameter ) );\n\t\tif ( binding == null || !binding.isBound() ) {\n\t\t\tthrow new IllegalStateException( \"Parameter value not yet bound : \" + param );\n\t\t}\n\t\tif ( binding.isMultiValued() ) {\n\t\t\t// TODO: THIS IS UNSOUND, we should really throw in this case\n\t\t\t//noinspection unchecked\n\t\t\treturn (T) binding.getBindValues();\n\t\t}\n\t\telse {\n\t\t\treturn binding.getBindValue();\n\t\t}\n\t}\n\n\t@Override\n\tpublic Object getParameterValue(@Nonnull String name) {\n\t\tsession.checkOpen( false );\n\t\tfinal var binding = getQueryParameterBindings().getBinding( name );\n\t\tif ( !binding.isBound() ) {\n\t\t\tthrow new IllegalStateException( \"The parameter named '\" + name + \"' has no argument\" );\n\t\t}","sourceCodeStart":919,"sourceCodeEnd":955,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/query/internal/AbstractCommonQueryContract.java#L919-L955","documentation":"Thrown (IllegalStateException) by getParameterValue(Parameter<T> param) when the parameter IS part of the query but has no binding yet: the resolved parameter's QueryParameterBinding is null or binding.isBound() is false. You are asking to read a value that was never set with setParameter. Note the adjacent TODO in the source: if the binding is multi-valued the raw bind-values List is returned with an unchecked cast, so type safety on that path is not guaranteed.","triggerScenarios":"Calling query.getParameterValue(param) before any query.setParameter(param, value). Reading a parameter in dynamic filter code where the parameter is optional and may legitimately be unset. Checking bound values after an exception aborted the binding loop midway.","commonSituations":"Generic query wrappers that iterate all getParameters() and log their values; test harnesses asserting bound arguments before binding happens; optional-parameter handling where 'not set' and 'set to null' were conflated.","solutions":["Bind every parameter before reading: query.setParameter(param, value) — including explicit null when the value is genuinely null","Check bound-ness first with query.isBound(param) (JPA Query method) before calling getParameterValue","Restructure wrapper code to read values only after the binding phase completes"],"exampleFix":"// before\nObject v = query.getParameterValue( param ); // IllegalStateException: not yet bound\n\n// after\nif ( query.isBound( param ) ) {\n    Object v = query.getParameterValue( param );\n} else {\n    query.setParameter( param, defaultValue );\n}","handlingStrategy":"validation","validationCode":"Parameter<?> p = query.getParameter( \"name\" );\nif ( !query.isBound( p ) ) {\n    query.setParameter( p, defaultValue );\n}\nObject v = query.getParameterValue( p );","typeGuard":null,"tryCatchPattern":"try {\n    return query.getParameterValue( param );\n} catch ( IllegalStateException e ) {\n    return null; // treat 'not yet bound' as absent\n}","preventionTips":["Bind all parameters before any read phase (loggers, auditors)","Use query.isBound(param) before getParameterValue","Bind explicit nulls for optional single-valued parameters so they count as bound"],"tags":["hibernate","query-parameters","parameter-binding","illegalstate"],"backgroundTag":"parameter-value-not-bound","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}