hibernate/hibernate-orm · error · IllegalArgumentException

Unrecognized 'hibernate.hbm2ddl.auto' setting: '%s'

Error message

Unrecognized 'hibernate.hbm2ddl.auto' setting: '%s'

What it means

hibernate.hbm2ddl.auto is interpreted by matching legacy hbm2ddl names, then JPA external names, then enum constant names. A trimmed value that matches none of them throws this IllegalArgumentException, listing the exact offending string so the bad token is easy to spot in config.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/tool/schema/Action.java:338

		}

		// prefer hbm2ddl names
		for ( var action : values() ) {
			final String hbm2ddlName = action.getExternalHbm2ddlName();
			if ( hbm2ddlName != null && hbm2ddlName.equals( name ) ) {
				return action;
			}
		}

		// then check JPA external names
		for ( var action : values() ) {
			final String jpaName = action.getExternalJpaName();
			if ( jpaName != null && jpaName.equals( name ) ) {
				return action;
			}
		}

		throw new IllegalArgumentException( "Unrecognized '" + HBM2DDL_AUTO + "' setting: '" + name + "'" );
	}

}

View on GitHub (pinned to fad1729dce)

Solutions

1. Correct the value to a supported one: none, validate, update, create, create-drop, create-only, drop, drop-only (JPA drop-and-create is also accepted).
2. Trace where the value comes from — spring.jpa.hibernate.ddl-auto, environment variables, bootstrap properties — and fix it at that source.

Example fix

# before
spring.jpa.hibernate.ddl-auto: validate-schema

# after
spring.jpa.hibernate.ddl-auto: validate

private static final Set<String> VALID_HBM2DDL = Set.of(
        "none", "validate", "update", "create", "create-drop",
        "create-only", "drop", "drop-only", "drop-and-create");

String token = ddlAuto == null ? null : ddlAuto.trim().toLowerCase(Locale.ROOT);
if (token != null && !VALID_HBM2DDL.contains(token)) {
    throw new IllegalStateException("Bad hibernate.hbm2ddl.auto value: " + ddlAuto);
}

When it happens

Trigger: Setting hibernate.hbm2ddl.auto to anything outside none, validate, update, create, create-drop, create-only, drop, drop-only (plus accepted JPA names): typos like "validate-schema", "update-only", "creat", or "drop_and_create" in wrong casing/form.

Common situations: A typo in spring.jpa.hibernate.ddl-auto forwarded into Hibernate; profile-specific overrides with wrong tokens; ops runbooks or env vars (HBM2DDL_AUTO) supplying bad values; docs or templates suggesting nonexistent values like "none-create".

Related errors

• Unrecognized JPA schema management action setting: '%s'
• Schema generation configuration indicated to include CREATE
• VALIDATE is not valid SchemaManagementTool action for script
• Unrecognized 'hibernate.hbm2ddl.jdbc_metadata_extraction_str
• Unrecognized schema generation source type: '%s'

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