{"record":{"id":"01ef856767f3cebc","repo":"hibernate/hibernate-orm","slug":"unable-to-locate-jdbcvaluedescriptor-for-column","errorCode":null,"errorMessage":"Unable to locate JdbcValueDescriptor for column `%s`","messagePattern":"Unable to locate JdbcValueDescriptor for column `(.+?)`","errorType":"exception","errorClass":"HibernateException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/action/queue/spi/bind/JdbcValueBindings.java","lineNumber":116,"sourceCode":"\t\t\t\t\t\t\t\tLocale.ROOT,\n\t\t\t\t\t\t\t\t\"Unable to bind parameter #%s - %s\",\n\t\t\t\t\t\t\t\tslot.jdbcPosition(),\n\t\t\t\t\t\t\t\tvaluesBySlot[i]\n\t\t\t\t\t\t)\n\t\t\t\t);\n\t\t\t}\n\t\t}\n\t}\n\n\tpublic static Object resolveValue(Object value) {\n\t\treturn value instanceof DelayedValueAccess handle ? handle.get() : value;\n\t}\n\n\tpublic void bindValue(Object columnValue, String columnName, ParameterUsage parameterUsage) {\n\t\tif ( bindTemplate != null ) {\n\t\t\tfinal BindSlot slot = bindTemplate.findSlot( columnName, parameterUsage );\n\t\t\tif ( slot == null ) {\n\t\t\t\tthrow new HibernateException( \"Unable to locate JdbcValueDescriptor for column `\" + columnName + \"`\" );\n\t\t\t}\n\t\t\tif ( !boundSlots[slot.index()] ) {\n\t\t\t\tvaluesBySlot[slot.index()] = columnValue;\n\t\t\t\tboundSlots[slot.index()] = true;\n\t\t\t}\n\t\t\treturn;\n\t\t}\n\n\t\tfinal var jdbcValueDescriptor = jdbcValueDescriptorAccess.resolveValueDescriptor(\n\t\t\t\ttableDescriptor.name(),\n\t\t\t\tcolumnName,\n\t\t\t\tparameterUsage\n\t\t);\n\t\tif ( jdbcValueDescriptor == null ) {\n\t\t\tthrow new HibernateException( \"Unable to locate JdbcValueDescriptor for column `\" + columnName + \"`\" );\n\t\t}\n\t\tbindingGroup.bindValue( columnName, columnValue, jdbcValueDescriptor );\n\t}","sourceCodeStart":98,"sourceCodeEnd":134,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/action/queue/spi/bind/JdbcValueBindings.java#L98-L134","documentation":"JdbcValueBindings.bindValue maps a (column, ParameterUsage) pair onto a parameter slot of the prepared mutation. When a bind template is active and findSlot(columnName, parameterUsage) returns null, the mutation statement has no parameter for that column/usage combination, so the value cannot be attached and HibernateException is thrown. It is almost always a name or usage mismatch between what the caller binds and what the mutation SQL declares.","triggerScenarios":"Calling bindValue with a column name that differs from the mapped name (case differences on case-sensitive databases, quoted identifiers, typos) or with the wrong ParameterUsage (e.g. binding a value as REGULAR when the parameter is RETURNING); custom mutation code binding columns that are not in the generated statement.","commonSituations":"Custom MutationExecutor / PreparableMutationOperation implementations; integrations that bind audit or revision columns; column renames in the mapping while stale code binds the old literal name.","solutions":["Log the mutation SQL and bind exactly the column names it declares, including case and quoting.","Pass the ParameterUsage that matches the parameter kind being bound (REGULAR, RETURNING, LIMIT...).","In custom binding code, derive names from the template/descriptor set instead of hard-coded literals.","If no custom code is involved, upgrade Hibernate - descriptor resolution regressions have occurred across versions."],"exampleFix":"// before\nbindings.bindValue(value, \"ACCOUNT_ID\", ParameterUsage.REGULAR); // mapped as 'accountId'\n// after\nbindings.bindValue(value, \"accountId\", ParameterUsage.REGULAR);","handlingStrategy":"validation","validationCode":"// derive column names from the mapping instead of hard-coded literals\nfor (SelectableMapping col : mutationTarget.getSelectableMappings()) {\n    bindings.bindValue(values.get(col.getSelectionExpression()), col.getSelectionExpression(), ParameterUsage.REGULAR);\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Bind with the exact selection expression from the mapping, preserving case and quoting","Match the ParameterUsage to the parameter kind (REGULAR vs RETURNING vs LIMIT)","Add a unit test that binds every mapped column of each mutated table"],"tags":["hibernate","mutation","parameter-binding","column-mismatch","flush"],"backgroundTag":"column-name-mismatch","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}