{"record":{"id":"f460b12115d3b81a","repo":"hibernate/hibernate-orm","slug":"uniquekey-already-exists","errorCode":null,"errorMessage":"UniqueKey {} already exists","messagePattern":"UniqueKey (.+?) already exists","errorType":"exception","errorClass":"MappingException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/mapping/Table.java","lineNumber":478,"sourceCode":"\t}\n\n\tpublic Index getIndex(String indexName) {\n\t\treturn indexes.get( indexName );\n\t}\n\n\tpublic Index addIndex(Index index) {\n\t\tfinal var current =  indexes.get( index.getName() );\n\t\tif ( current != null ) {\n\t\t\tthrow new MappingException( \"Index \" + index.getName() + \" already exists\" );\n\t\t}\n\t\tindexes.put( index.getName(), index );\n\t\treturn index;\n\t}\n\n\tpublic UniqueKey addUniqueKey(UniqueKey uniqueKey) {\n\t\tfinal var current = uniqueKeys.get( uniqueKey.getName() );\n\t\tif ( current != null ) {\n\t\t\tthrow new MappingException( \"UniqueKey \" + uniqueKey.getName() + \" already exists\" );\n\t\t}\n\t\tuniqueKeys.put( uniqueKey.getName(), uniqueKey );\n\t\treturn uniqueKey;\n\t}\n\n\t/**\n\t * Mark the given column unique and assign a name to the unique key.\n\t * <p>\n\t * This method does not add a {@link UniqueKey} to the table itself!\n\t */\n\tpublic void createUniqueKey(Column column, MetadataBuildingContext context) {\n\t\tfinal String keyName = context.getBuildingOptions().getImplicitNamingStrategy()\n\t\t\t\t.determineUniqueKeyName( new ImplicitUniqueKeyNameSource() {\n\t\t\t\t\t@Override\n\t\t\t\t\tpublic Identifier getTableName() {\n\t\t\t\t\t\treturn name;\n\t\t\t\t\t}\n","sourceCodeStart":460,"sourceCodeEnd":496,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/mapping/Table.java#L460-L496","documentation":"Table.addUniqueKey(UniqueKey) mirrors addIndex: it registers a unique constraint by name on a table and throws when a UniqueKey with that name already exists in uniqueKeys. Unique constraint names share the database namespace per table/schema, so Hibernate refuses silent overwriting and reports the colliding name.","triggerScenarios":"Two @UniqueConstraint(name = \"uk_x\", columnNames = {...}) entries resolving to the same table name; @Table(uniqueConstraints = ...) duplicated across SINGLE_TABLE subclasses that share one physical table; hbm.xml <unique-key name=\"x\"/> declared twice for one table; programmatic table.addUniqueKey(...) called twice with the same name.","commonSituations":"Inheritance hierarchies where each subclass adds the same named constraint to the shared root table; refactors that moved @UniqueConstraint between class-level and property-level annotations leaving duplicates; merging XML mappings; DDL-generation tests after annotations were copy-pasted between related entities.","solutions":["Locate all @UniqueConstraint (and <unique-key>) declarations for the table and give each a distinct, descriptive name like uk_orders_order_number.","Remove redundant duplicates that constrain the same column set.","For programmatic mapping, check uniqueKeys.get(name) (or table.getUniqueKey(name)) before adding.","Use a consistent naming scheme including the table name to avoid cross-subclass collisions."],"exampleFix":"// before\n@Table(name = \"users\", uniqueConstraints = {\n    @UniqueConstraint(name = \"uk_email\", columnNames = \"email\")\n})\npublic class User { ... }\n@AttributeOverrides... // subclass adds uk_email again to same table\n\n// after — one constraint only, clearly named\n@Table(name = \"users\", uniqueConstraints = {\n    @UniqueConstraint(name = \"uk_users_email\", columnNames = \"email\")\n})\npublic class User { ... }","handlingStrategy":"validation","validationCode":"// programmatic mapping: check before add\nif (table.getUniqueKey(\"uk_users_email\") != null) {\n    // constraint already registered — skip or rename\n} else {\n    table.addUniqueKey(uk);\n}","typeGuard":null,"tryCatchPattern":"try {\n    metadata.buildMetadata().validate();\n} catch (MappingException e) {\n    if (e.getMessage().matches(\"UniqueKey .+ already exists\")) {\n        // duplicate @UniqueConstraint/<unique-key> name — dedupe\n    }\n    throw e;\n}","preventionTips":["Prefix unique constraint names with the table name (uk_orders_order_number).","Declare shared-table constraints once, on the hierarchy root.","CI lint: gather all @UniqueConstraint names per table and fail on duplicates."],"tags":["hibernate","unique-constraint","schema","duplicate-name","orm-mapping"],"backgroundTag":"duplicate-constraint-name","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}