hibernate/hibernate-orm · error · IllegalArgumentException

Unrecognized JPA schema management action setting: '%s'

Error message

Unrecognized JPA schema management action setting: '%s'

What it means

Hibernate converts the JPA schema management action setting (jakarta.persistence.schema-generation.database-action) into an internal Action by matching legacy hbm2ddl aliases, then JPA external names, then enum constant names. A value matching none of them — a typo, an unsupported word, or an unresolved placeholder — ends in this IllegalArgumentException carrying the raw value.

Source

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

			}
		}

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

		// lastly, look at the enum name
		for ( var action : values() ) {
			if ( action.name().equals( name ) ) {
				return action;
			}
		}

		throw new IllegalArgumentException( "Unrecognized JPA schema management action setting: '" + value + "'" );
	}

	private static Action interpretJpaSchemaManagementAction(SchemaManagementAction action) {
		return switch ( action ) {
			case NONE -> NONE;
			case CREATE -> CREATE_ONLY;
			case DROP -> DROP;
			case DROP_AND_CREATE -> CREATE;
			case VALIDATE -> VALIDATE;
			case POPULATE -> POPULATE;
		};
	}

	/**
	 * Interpret the value of the old-school Hibernate configuration property
	 * {@value org.hibernate.cfg.SchemaToolingSettings#HBM2DDL_AUTO} as an
	 * instance of {@link Action}.
	 *

View on GitHub (pinned to fad1729dce)

Solutions

1. Use a supported value: none, create, create-only, drop, drop-only, create-drop, drop-and-create, validate, update (matching is case-insensitive and covers the JPA names).
2. Inspect the raw property for typos, whitespace, and unresolved ${placeholders} in persistence.xml, YAML, or environment variables, and fix it at the source.

Example fix

# before
<property name="jakarta.persistence.schema-generation.database-action" value="create-drip"/>

# after
<property name="jakarta.persistence.schema-generation.database-action" value="drop-and-create"/>

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

if (value != null) {
    String token = value.toString().trim().toLowerCase(Locale.ROOT);
    if (!VALID_ACTIONS.contains(token)) {
        throw new IllegalStateException("Unsupported schema action: " + value);
    }
}

When it happens

Trigger: Action interpretation receiving strings like "createonly", "Drop and Create", "refresh", or a placeholder that was never substituted ("${ddl.action}"); none match a legacy alias, JPA external name, or enum name, so interpretation throws.

Common situations: Env-var or placeholder typos; mixing Hibernate's create-drop with JPA's drop-and-create vocabulary; Spring forwarding a misspelled spring.jpa.hibernate.ddl-auto value; ops templates with stray casing or punctuation.

Related errors

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

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