{"record":{"id":"b3352a01beda116f","repo":"hibernate/hibernate-orm","slug":"could-not-locate-binding-s-s","errorCode":null,"errorMessage":"Could not locate binding [%s : %s]","messagePattern":"Could not locate binding \\[(.+?) : (.+?)\\]","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/engine/jdbc/mutation/spi/BindingGroup.java","lineNumber":106,"sourceCode":"\t\tbindings.clear();\n\t}\n\n\t@Nullable public Binding findBinding(String columnName, ParameterUsage usage) {\n\t\tfor ( Binding binding : bindings ) {\n\t\t\tif ( binding.getValueDescriptor().getUsage() == usage\n\t\t\t\t&& binding.getColumnName().equals( columnName ) ) {\n\t\t\t\treturn binding;\n\t\t\t}\n\t\t}\n\t\treturn null;\n\t}\n\n\tpublic Binding getBinding(String columnName, ParameterUsage usage) {\n\t\tfinal Binding binding = findBinding( columnName, usage );\n\t\tif ( binding != null ) {\n\t\t\treturn binding;\n\t\t}\n\t\tthrow new IllegalArgumentException( String.format( Locale.ROOT,\n\t\t\t\t\"Could not locate binding [%s : %s]\",\n\t\t\t\tusage.toString(),\n\t\t\t\tcolumnName\n\t\t) );\n\t}\n}\n","sourceCodeStart":88,"sourceCodeEnd":113,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/engine/jdbc/mutation/spi/BindingGroup.java#L88-L113","documentation":"BindingGroup.getBinding(columnName, usage) looks up a previously bound value by column name and ParameterUsage; if bindValue was never called for that combination it throws IllegalArgumentException 'Could not locate binding [USAGE : column]'. It is an internal consistency check in the mutation-execution group machinery: something asked for a parameter that was never bound.","triggerScenarios":"Custom MutationExecutor or custom mutation SQL that expects a parameter (column/usage pair) the binder never set; mismatches between the values bound via JdbcValueBindings and the parameters expected by the prepared statement; corner-case bugs in Hibernate's own group/batch handling.","commonSituations":"Projects with custom @SQLInsert/@SQLUpdate annotations or custom MutationExecutorService implementations after upgrading Hibernate (the binding contract changed across 6.x); soft-delete/version/tenant columns missing from custom SQL.","solutions":["If you use custom SQL mutations, make sure every parameter Hibernate binds appears in your SQL placeholders and vice versa (including version, discriminator and tenant columns)","Remove custom executors/SQL temporarily to confirm the standard path works, then re-add piece by piece","Upgrade to the latest Hibernate 6.x patch — several binding-lookup invariant breaks were fixed","If it reproduces on vanilla mappings, capture the entity mapping and stack trace and report it upstream"],"exampleFix":"// before: custom SQL missing the version parameter\n@SQLUpdate(sql = \"UPDATE doc SET content=? WHERE id=?\")\n\n// after: bind every column Hibernate expects\n@SQLUpdate(sql = \"UPDATE doc SET content=?, version=? WHERE id=? AND version=?\")","handlingStrategy":"try-catch","validationCode":"// for custom SQL: bind every column/usage the mutation expects before execution\nfor (ParameterBinding p : expectedParameters(mutation)) {\n    if (!bindings.isBound(p.table(), p.column())) {\n        throw new IllegalStateException(\"unbound parameter \" + p);\n    }\n}","typeGuard":null,"tryCatchPattern":"try {\n    session.flush();\n}\ncatch (IllegalArgumentException e) {\n    if (e.getMessage() != null && e.getMessage().startsWith(\"Could not locate binding\")) {\n        // custom SQL/executor mismatch: compare expected vs bound parameter lists\n    }\n}","preventionTips":["List version/discriminator/tenant parameters in custom SQL mutations","Re-validate custom executors after every Hibernate upgrade","Report clean reproductions upstream — often core bugs, not your code"],"tags":["mutation","binding","custom-sql","batch","hibernate"],"backgroundTag":"missing-parameter-binding","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}