hibernate/hibernate-orm · error · SchemaManagementException

Unique-key mismatch - `%s` on table `%s`

Error message

Unique-key mismatch - `%s` on table `%s`

What it means

Unique-key validation: an index with the declared unique-key name exists in JDBC metadata, but its column list disagrees with the mapped constraint - different column count or a column name at position i differs (position-sensitive comparison, same as index validation). The mapped and physical unique key must cover the same columns in the same order.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/tool/schema/internal/AbstractSchemaValidator.java:297

			var matches = true;
			assert uk.getColumns().size() == uk.getColumnSpan();
			if ( uk.getColumnSpan() != ukInfo.getIndexedColumns().size() ) {
				matches = false;
			}
			else {
				for ( int i = 0; i < uk.getColumns().size(); i++ ) {
					final Column column = uk.getColumns().get( i );
					final ColumnInformation columnInfo = ukInfo.getIndexedColumns().get( i );
					if ( !column.getName().equals( columnInfo.getColumnIdentifier().getText() ) ) {
						matches = false;
						break;
					}
				}
			}

			if ( !matches ) {
				throw new SchemaManagementException(
						String.format(
								ROOT,
								"Unique-key mismatch - `%s` on table `%s`",
								name.render( dialect ),
								tableInformation.getName().render()
						)
				);
			}
		} );
	}

	protected void validateSequence(Sequence sequence, SequenceInformation sequenceInformation) {
		if ( sequenceInformation == null ) {
			throw new SchemaManagementException(
					String.format( "Schema validation: missing sequence [%s]", sequence.getName() )
			);
		}

View on GitHub (pinned to fad1729dce)

Solutions

  1. Realign the constraint to the mapping: ALTER TABLE ... DROP CONSTRAINT <name>; ALTER TABLE ... ADD CONSTRAINT <name> UNIQUE (col1, col2); with exactly the mapped columns and order.
  2. Or update @UniqueConstraint(columnNames = {...}) to match the physical definition.
  3. If intentional divergence is required, remove the name from the mapping or set unique_key_validation=NONE for that profile.

Example fix

// before: mapping says (email) but the DB constraint is (email, tenant_id)
@Table(name = "customer", uniqueConstraints =
    @UniqueConstraint(name = "uk_customer_email", columnNames = "email"))

// after: match the physical constraint
@Table(name = "customer", uniqueConstraints =
    @UniqueConstraint(name = "uk_customer_email", columnNames = {"email", "tenant_id"}))
Defensive patterns

Strategy: validation

Validate before calling

// Before validate, compare the mapped unique-key column list/order with JDBC metadata
try (Connection c = dataSource.getConnection();
     ResultSet rs = c.getMetaData().getIndexInfo(null, null, "customer", false, true)) {
    List<String> actual = new ArrayList<>();
    while (rs.next()) {
        if ("uk_customer_email".equalsIgnoreCase(rs.getString("INDEX_NAME"))) {
            actual.add(rs.getString("COLUMN_NAME"));
        }
    }
    if (!List.of("email", "tenant_id").equals(actual)) {
        throw new IllegalStateException("uk_customer_email columns mismatch: " + actual);
    }
}

Try / catch

try {
    new SchemaValidator().validate(metadata, serviceRegistry);
} catch (SchemaManagementException e) {
    if (e.getMessage() != null && e.getMessage().startsWith("Unique-key mismatch")) {
        // realign: rebuild the constraint with the mapped columns/order or update columnNames
    }
    throw e;
}

Prevention

When it happens

Trigger: validate with hibernate.tooling.schema.unique_key_validation=NAMED/ALL where the DB constraint covers different columns or order than @UniqueConstraint(columnNames = {...}) declares: the constraint was broadened/narrowed by a DBA; multi-tenant migrations added tenant_id to unique constraints; a column rename left the physical constraint referencing the old column.

Common situations: Composite unique keys evolved in the database but not in the mapping (or vice versa); tenancy refactors adding a discriminator column to uniqueness; Hibernate-version upgrades re-enabling unique-key validation against long-diverged schemas.

Related errors

AI-assisted analysis of hibernate/hibernate-orm@fad1729dce (2026-08-22). Data as JSON: /api/errors/698f26983baabdf4. Report an issue: GitHub.