{"record":{"id":"6aaa543531dc49b5","repo":"hibernate/hibernate-orm","slug":"unique-key-constraint-involves-formulas","errorCode":null,"errorMessage":"Unique key constraint involves formulas","messagePattern":"Unique key constraint involves formulas","errorType":"exception","errorClass":"MappingException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/mapping/SimpleValue.java","lineNumber":412,"sourceCode":"\n\tprotected boolean hasAuxiliaryColumnInPrimaryKey(PersistentClass referencedEntity) {\n\t\treturn referencedEntity.getRootClass().isAuxiliaryColumnInPrimaryKey();\n\t}\n\n\tprotected boolean hasAuxiliaryColumnInPrimaryKey(String entityName) {\n\t\tif ( entityName == null ) {\n\t\t\treturn false;\n\t\t}\n\t\telse {\n\t\t\tfinal var referencedEntity = metadata.getEntityBinding( entityName );\n\t\t\treturn referencedEntity != null && hasAuxiliaryColumnInPrimaryKey( referencedEntity );\n\t\t}\n\t}\n\n\t@Override\n\tpublic void createUniqueKey(MetadataBuildingContext context) {\n\t\tif ( hasFormula() ) {\n\t\t\tthrow new MappingException( \"Unique key constraint involves formulas\" );\n\t\t}\n\t\tgetTable().createUniqueKey( getConstraintColumns(), context );\n\t}\n\n\t@Internal\n\tpublic void setCustomIdGeneratorCreator(GeneratorCreator customIdGeneratorCreator) {\n\t\tthis.customIdGeneratorCreator = customIdGeneratorCreator;\n\t}\n\n\t@Internal\n\tpublic GeneratorCreator getCustomIdGeneratorCreator() {\n\t\treturn customIdGeneratorCreator;\n\t}\n\n\t@Override\n\t@Remove\n\tpublic Generator createGenerator(\n\t\t\tDialect dialect,","sourceCodeStart":394,"sourceCodeEnd":430,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/mapping/SimpleValue.java#L394-L430","documentation":"createUniqueKey() was invoked on a value that contains formulas. SQL unique constraints can only cover real columns, so SimpleValue refuses to build a unique key when hasFormula() is true. The mapping asks the database to enforce uniqueness over a computed expression, which a constraint cannot do.","triggerScenarios":"An hbm property marked unique=true whose value contains a formula element; uniqueness requested on a mapping that mixes in formulas; programmatic unique-key creation on a value holding Formula entries.","commonSituations":"Formula-based derived properties accidentally marked unique; mapping tools that set unique broadly; attempts to enforce uniqueness of computed values like upper(name).","solutions":["Remove the unique flag from the formula-based property","Put the unique constraint on the real underlying column instead","If uniqueness of a computed value is required, use a real (possibly generated) column with a DB-level constraint, or enforce it in application code"],"exampleFix":"// before\n<property name=\"normalizedCode\" unique=\"true\">\n  <formula>upper(code)</formula>\n</property>\n\n// after\n<property name=\"code\" unique=\"true\"/>\n<!-- drop uniqueness on the formula -->","handlingStrategy":"validation","validationCode":"for (PersistentClass pc : metadata.getEntityBindings()) {\n    for (Property p : pc.getProperties()) {\n        if (p.getValue() instanceof SimpleValue sv && sv.hasFormula() && sv.isUnique()) {\n            // uniqueness requested on a formula; remove the unique flag or map a real column\n        }\n    }\n}","typeGuard":"static boolean isUniqueOverFormula(SimpleValue sv) {\n    return sv.hasFormula() && sv.isUnique();\n}","tryCatchPattern":null,"preventionTips":["Never request uniqueness on formula-based properties","Enforce uniqueness of computed values with real or generated columns plus DB constraints"],"tags":["hibernate","orm","unique-constraint","formula","ddl"],"backgroundTag":"invalid-unique-constraint","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}