hibernate/hibernate-orm · error · IllegalArgumentException

Unrecognized 'hibernate.hbm2ddl.jdbc_metadata_extraction_str

Error message

Unrecognized 'hibernate.hbm2ddl.jdbc_metadata_extraction_strategy' value: '%s'

What it means

hibernate.hbm2ddl.jdbc_metadata_extraction_strategy selects how JDBC metadata is read during schema validate/update: grouped (one grouped extraction round, the default — an empty/blank value also falls back to it) or individually (per-table lookups). Any other trimmed value throws this IllegalArgumentException, since matching is case-insensitive equality against exactly those two strategy names.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/tool/schema/JdbcMetadataAccessStrategy.java:72

			return interpretHbm2ddlSetting( options.get( HBM2DDL_JDBC_METADATA_EXTRACTOR_STRATEGY ) );
		}
	}

	public static JdbcMetadataAccessStrategy interpretHbm2ddlSetting(Object value) {
		if ( value == null ) {
			return GROUPED;
		}
		else {
			final String name = value.toString().trim();
			if ( name.isEmpty() ) {
				return GROUPED;
			}
			for ( var strategy: values() ) {
				if ( strategy.toString().equalsIgnoreCase(name) ) {
					return strategy;
				}
			}
			throw new IllegalArgumentException( "Unrecognized '" + HBM2DDL_JDBC_METADATA_EXTRACTOR_STRATEGY + "' value: '" + value + "'");
		}
	}
}

View on GitHub (pinned to fad1729dce)

Solutions

1. Set the value to grouped or individually — or remove the property entirely to get the grouped default.
2. Fix token typos and variants: 'individual' is not accepted; the exact strings are 'grouped' and 'individually'.

Example fix

# before
hibernate.hbm2ddl.jdbc_metadata_extraction_strategy=individual

# after
hibernate.hbm2ddl.jdbc_metadata_extraction_strategy=individually

private static final Set<String> VALID_STRATEGIES = Set.of("grouped", "individually");

String token = strategy == null ? "" : strategy.trim().toLowerCase(Locale.ROOT);
if (!token.isEmpty() && !VALID_STRATEGIES.contains(token)) {
    throw new IllegalStateException("Bad jdbc_metadata_extraction_strategy: " + strategy);
}

When it happens

Trigger: Setting the property to "individual", "grouped-by-table", "single", or a typo — none equal grouped/individually case-insensitively, so JdbcMetadataAccessStrategy.interpret throws during bootstrap.

Common situations: Tuning schema-validation performance against slow database metadata catalogs; copying the key/value from blog posts that use a wrong token like 'individual'; leftover experiments committed into property files.

Related errors

• Unable to determine Dialect without JDBC metadata (please se
• Unable to access JDBC metadata
• Unrecognized JPA schema management action setting: '%s'
• Unrecognized 'hibernate.hbm2ddl.auto' setting: '%s'
• Attempt to resolve foreign key metadata from JDBC metadata f

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