hibernate/hibernate-orm · error · IllegalArgumentException

Unrecognized 'hibernate.hbm2ddl.auto' setting

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.

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

• Schema generation configuration indicated to include CREATE…
• Unrecognized JPA schema management action setting
• VALIDATE is not valid SchemaManagementTool action for…
• Unrecognized…
• Unrecognized schema generation source type

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

Appendix: 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)