hibernate/hibernate-orm · error · SchemaExtractionException

Primary Key information was missing for key [%s] on table [%

Error message

Primary Key information was missing for key [%s] on table [%s] at KEY_SEQ = %s

What it means

SchemaExtractionException from NameSpacePrimaryKeysInformation.validate(): while validating assembled primary-key metadata, the ordered column list of some table's PK contains a null at 1-based position KEY_SEQ = i. Hibernate slots PK columns from DatabaseMetaData.getPrimaryKeys() into positions numbered by KEY_SEQ; a hole means the driver reported non-contiguous, duplicated, or truncated KEY_SEQ values - inconsistent JDBC metadata.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/tool/schema/extract/spi/NameSpacePrimaryKeysInformation.java:44

		primaryKeys.put( tableInformation.getName().getTableName().getText(), primaryKeyInformation );
	}

	public @Nullable PrimaryKeyInformation getPrimaryKeyInformation(Table table) {
		return primaryKeys.get( identifierHelper.toMetaDataObjectName( table.getQualifiedTableName().getTableName() ) );
	}

	public @Nullable PrimaryKeyInformation getPrimaryKeyInformation(String tableName) {
		return primaryKeys.get( tableName );
	}

	public void validate() {
		for ( Map.Entry<String, PrimaryKeyInformation> entry : primaryKeys.entrySet() ) {
			final var tableName = entry.getKey();
			final var primaryKeyInformation = entry.getValue();
			int i = 1;
			for ( ColumnInformation column : primaryKeyInformation.getColumns() ) {
				if ( column == null ) {
					throw new SchemaExtractionException(
							"Primary Key information was missing for key [" +
							primaryKeyInformation.getPrimaryKeyIdentifier() + "] on table [" + tableName +
							"] at KEY_SEQ = " + i
					);
				}
				i++;
			}
		}
	}
}

View on GitHub (pinned to fad1729dce)

Solutions

Upgrade/align the JDBC driver with the database version and rerun.
Inspect the PK metadata (SELECT constraint_name, ordinal_position, column_name FROM information_schema.key_column_usage WHERE table_name = '<table>') and rebuild the constraint so ordinal positions are contiguous: ALTER TABLE ... DROP CONSTRAINT ... then ADD CONSTRAINT ... PRIMARY KEY (...).
If the table is partitioned or inherited, validate against a partition/leaf table or exclude it from hbm2ddl validation.
Adopt Flyway/Liquibase for schema management to avoid dependence on driver PK metadata.

Example fix

-- before: driver reports KEY_SEQ 1,3 for orders_pkey -> null at slot 2
SELECT constraint_name, ordinal_position, column_name
FROM information_schema.key_column_usage
WHERE table_name = 'orders';

-- after: rebuild the constraint so catalog rows are contiguous
ALTER TABLE orders DROP CONSTRAINT orders_pkey;
ALTER TABLE orders ADD CONSTRAINT orders_pkey PRIMARY KEY (id, tenant_id);

Defensive patterns

Strategy: validation

Validate before calling

// Check KEY_SEQ contiguity for the primary keys of the tables being validated
try (Connection c = dataSource.getConnection();
     ResultSet rs = c.getMetaData().getPrimaryKeys(null, null, "orders")) {
    int expected = 1;
    while (rs.next()) {
        if (rs.getShort("KEY_SEQ") != expected) {
            System.err.println("PK metadata hole at KEY_SEQ " + expected + " for " + rs.getString("PK_NAME"));
        }
        expected++;
    }
}

Try / catch

try {
    new SchemaValidator().validate(metadata, serviceRegistry);
} catch (SchemaManagementException e) {
    if (e.getMessage() != null && e.getMessage().contains("Primary Key information was missing")) {
        // parse key/table/KEY_SEQ from the message, rebuild the PK constraint, re-run
    }
    throw e;
}

Prevention

Keep the JDBC driver aligned with the database version
Avoid hbm2ddl validation on partitioned/inherited parent tables with partial PK metadata
Validate in CI against a schema built by the same migrations used in production

When it happens

Trigger: Primary-key extraction on databases/drivers whose getPrimaryKeys() result skips a KEY_SEQ value, duplicates one, or returns fewer rows than the key's column count; the later validate() pass finds the null slot and throws with the key name, table name, and offending position. Seen with certain Oracle/DB2/SQL Server driver versions, partitioned tables, and PostgreSQL inheritance/partition parents whose PK metadata is only partially reported.

Common situations: hbm2ddl validate after a driver downgrade; validating against a partitioned parent table; DB2 z/OS with legacy drivers; catalogs left inconsistent by online DDL churn; CI validating against a stale replica.

Related errors

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