{"record":{"id":"a7dbefe4cbe15199","repo":"hibernate/hibernate-orm","slug":"attempt-to-resolve-foreign-key-metadata-from-jdbc","errorCode":null,"errorMessage":"Attempt to resolve foreign key metadata from JDBC metadata failed to find column mappings for foreign key named [%s]","messagePattern":"Attempt to resolve foreign key metadata from JDBC metadata failed to find column mappings for foreign key named \\[(.+?)\\]","errorType":"exception","errorClass":"SchemaManagementException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/tool/schema/extract/internal/AbstractInformationExtractorImpl.java","lineNumber":1637,"sourceCode":"\n\tprotected static class ForeignKeyBuilderImpl implements ForeignKeyBuilder {\n\t\tprivate final Identifier foreignKeyIdentifier;\n\t\tprivate final List<ForeignKeyInformation.ColumnReferenceMapping> columnMappingList = new ArrayList<>();\n\n\t\tpublic ForeignKeyBuilderImpl(Identifier foreignKeyIdentifier) {\n\t\t\tthis.foreignKeyIdentifier = foreignKeyIdentifier;\n\t\t}\n\n\t\t@Override\n\t\tpublic ForeignKeyBuilder addColumnMapping(ColumnInformation referencing, ColumnInformation referenced) {\n\t\t\tcolumnMappingList.add( new ColumnReferenceMappingImpl( referencing, referenced ) );\n\t\t\treturn this;\n\t\t}\n\n\t\t@Override\n\t\tpublic ForeignKeyInformationImpl build() {\n\t\t\tif ( columnMappingList.isEmpty() ) {\n\t\t\t\tthrow new SchemaManagementException(\n\t\t\t\t\t\t\"Attempt to resolve foreign key metadata from JDBC metadata failed to find \" +\n\t\t\t\t\t\t\"column mappings for foreign key named [\" + foreignKeyIdentifier.getText() + \"]\"\n\t\t\t\t);\n\t\t\t}\n\t\t\treturn new ForeignKeyInformationImpl( foreignKeyIdentifier, columnMappingList );\n\t\t}\n\t}\n\n\tprivate QualifiedTableName extractPrimaryKeyTableName(ResultSet resultSet) throws SQLException {\n\t\treturn new QualifiedTableName(\n\t\t\t\ttoIdentifier( resultSet.getString( getResultSetPrimaryKeyCatalogLabel() ) ),\n\t\t\t\ttoIdentifier( resultSet.getString( getResultSetPrimaryKeySchemaLabel() ) ),\n\t\t\t\ttoIdentifier( resultSet.getString( getResultSetPrimaryKeyTableLabel() ) ) );\n\t}\n\n\tprivate QualifiedTableName extractTableName(ResultSet resultSet) throws SQLException {\n\t\treturn new QualifiedTableName(\n\t\t\t\ttoIdentifier( resultSet.getString( getResultSetCatalogLabel() ) ),","sourceCodeStart":1619,"sourceCodeEnd":1655,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/tool/schema/extract/internal/AbstractInformationExtractorImpl.java#L1619-L1655","documentation":"Thrown by Hibernate's JDBC schema extractor while reading foreign-key metadata: DatabaseMetaData.getImportedKeys() reported a foreign key by name, but after grouping the result-set rows for that key, zero referencing/referenced column pairs could be collected, so ForeignKeyInformation cannot be built. It is a consistency check between what the driver advertises and what Hibernate can map, and almost always indicates a JDBC driver/database mismatch or an exotic foreign key rather than a broken entity mapping.","triggerScenarios":"Running schema tooling that extracts live metadata (hibernate.hbm2ddl.auto=validate or update, SchemaValidator/SchemaUpdate, or a custom InformationExtractor pass). AbstractInformationExtractorImpl groups getImportedKeys() rows per FK name, calls addColumnMapping per row, and ForeignKeyBuilder.build() throws when the group's columnMappingList is empty. Produced by drivers returning FK rows with null/unknown FKCOLUMN_NAME or PKCOLUMN_NAME, cross-schema or self-referencing keys poorly reported by old drivers, or catalog stats left stale by renames.","commonSituations":"hbm2ddl validate in CI with an old MySQL Connector/J, jTDS, or a driver version lagging behind an upgraded DB server; Oracle schemas where the FK references a table in another schema; MariaDB/MySQL after table renames; mixing DB version N+1 with driver version N-1.","solutions":["Upgrade the JDBC driver to a version matching the database server, then rerun validate/update.","Inspect the named FK in the database (SELECT * FROM information_schema.KEY_COLUMN_USAGE WHERE CONSTRAINT_NAME = '<fk name>') and drop/recreate it so its column metadata is consistent.","Verify the connection resolves the expected catalog/schema (hibernate.default_catalog / hibernate.default_schema) so the key is not read from an unexpected namespace.","If the driver cannot be fixed, move schema management to Flyway/Liquibase, which diffs scripts instead of JDBC FK metadata."],"exampleFix":"// before: DB server upgraded, driver kept old -> getImportedKeys() returns a key with no columns\n// pom.xml\n<dependency>\n  <groupId>mysql</groupId>\n  <artifactId>mysql-connector-java</artifactId>\n  <version>5.1.34</version>\n</dependency>\n\n// after: driver matched to the server major version\n<dependency>\n  <groupId>com.mysql</groupId>\n  <artifactId>mysql-connector-j</artifactId>\n  <version>8.4.0</version>\n</dependency>","handlingStrategy":"try-catch","validationCode":"// Before running hbm2ddl validate/update, probe FK metadata for the tables involved\ntry (Connection c = dataSource.getConnection();\n     ResultSet rs = c.getMetaData().getImportedKeys(null, null, \"orders\")) {\n    while (rs.next()) {\n        String fk = rs.getString(\"FK_NAME\");\n        if (fk == null || rs.getString(\"FKCOLUMN_NAME\") == null || rs.getString(\"PKCOLUMN_NAME\") == null) {\n            System.err.println(\"Incomplete JDBC FK metadata for \" + fk + \" - fix driver/schema before hbm2ddl\");\n        }\n    }\n}","typeGuard":null,"tryCatchPattern":"try {\n    new SchemaValidator().validate(metadata, serviceRegistry);\n} catch (SchemaManagementException e) {\n    if (e.getMessage() != null && e.getMessage().contains(\"failed to find column mappings for foreign key\")) {\n        // driver metadata problem, not mapping drift: capture the FK name, align driver/DB, re-run\n    }\n    throw e;\n}","preventionTips":["Keep the JDBC driver version in lockstep with the database server version","Run hbm2ddl validate in CI against a schema produced by the exact migrations used in production","Prefer Flyway/Liquibase for production schema management instead of hbm2ddl validate/update"],"tags":["hibernate","schema-management","jdbc-metadata","foreign-key","hbm2ddl"],"backgroundTag":"jdbc-metadata-extraction","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}