{"record":{"id":"553d9cf9853f26a6","repo":"hibernate/hibernate-orm","slug":"constraint-involves-a-formula","errorCode":null,"errorMessage":"constraint involves a formula: {}","messagePattern":"constraint involves a formula: (.+?)","errorType":"exception","errorClass":"MappingException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/mapping/Constraint.java","lineNumber":56,"sourceCode":"\n\tpublic String getOptions() {\n\t\treturn options;\n\t}\n\n\tpublic void setOptions(String options) {\n\t\tthis.options = options;\n\t}\n\n\tpublic void addColumn(Column column) {\n\t\tif ( !columns.contains( column ) ) {\n\t\t\tcolumns.add( column );\n\t\t}\n\t}\n\n\tpublic void addColumns(Value value) {\n\t\tfor ( var selectable : value.getSelectables() ) {\n\t\t\tif ( selectable.isFormula() ) {\n\t\t\t\tthrow new MappingException( \"constraint involves a formula: \" + name );\n\t\t\t}\n\t\t\telse {\n\t\t\t\taddColumn( (Column) selectable );\n\t\t\t}\n\t\t}\n\t}\n\n\t/**\n\t * @return true if this constraint already contains a column with same name.\n\t */\n\tpublic boolean containsColumn(Column column) {\n\t\treturn columns.contains( column );\n\t}\n\n\tpublic int getColumnSpan() {\n\t\treturn columns.size();\n\t}\n","sourceCodeStart":38,"sourceCodeEnd":74,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/mapping/Constraint.java#L38-L74","documentation":"Constraint#addColumns throws when a primary key or unique constraint is being built over a Value that contains a formula instead of a physical column. Databases cannot enforce constraints on computed select fragments, so Hibernate refuses the mapping instead of generating invalid DDL.","triggerScenarios":"A composite id containing a formula-mapped part (hbm <key-property formula=\"...\"> or a formula inside the id value); a unique key declared over properties where one is mapped with @Formula; an association used as id or in a unique constraint where part of the join comes from @JoinColumnOrFormula's formula side.","commonSituations":"Using @Formula for derived values and then referencing those values in ids or unique constraints; legacy hbm mappings mixing <column> and <formula> inside constrained elements; trying to enforce uniqueness on a read-only computed field.","solutions":["Map constrained parts (id members, PK columns, unique key members) to real database columns instead of formulas.","Move the formula-derived value out of the constrained component into a normal read-only property.","If uniqueness must be enforced on a computed value, use a database generated column plus a real constraint."],"exampleFix":"<!-- before -->\n<composite-id name=\"id\" class=\"com.acme.CompId\">\n    <key-property name=\"code\"/>\n    <key-property name=\"derived\" formula=\"upper(code)\"/>\n</composite-id>\n\n<!-- after -->\n<composite-id name=\"id\" class=\"com.acme.CompId\">\n    <key-property name=\"code\"/>\n    <key-property name=\"derived\" column=\"derived_col\"/>\n</composite-id>","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n    metadata = sources.buildMetadata();\n} catch (MappingException e) {\n    // message contains the constraint name - locate it in the mappings\n    // and check its members for @Formula / <formula> parts\n    throw e;\n}","preventionTips":["Never reference @Formula-mapped properties inside ids, @EmbeddedId classes, or unique constraint definitions.","Review any <formula> elements inside hbm <composite-id>, <properties>, or key mappings.","Generate DDL in CI (create then drop) so invalid constraints fail the build."],"tags":["hibernate","orm","mapping","formula","constraint","unique-key","primary-key"],"backgroundTag":"formula-in-constraint","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}