hibernate/hibernate-orm · error · IllegalArgumentException

Unknown ActionQueue implementation: %s. Valid values are 'gr

Error message

Unknown ActionQueue implementation: %s. Valid values are 'graph' and 'legacy'.

What it means

At SessionFactory bootstrap Hibernate parses the hibernate.flush.queue.type setting (FlushSettings.FLUSH_QUEUE_TYPE) through QueueType.fromSetting. Only 'graph' (the new 8.0 graph-based ActionQueue, the default) and 'legacy' (the traditional hard-coded-ordering queue) are accepted, case-insensitively; any other string throws IllegalArgumentException and startup fails. The message deliberately lists the valid values.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/action/queue/spi/QueueType.java:40

	/// which requires hard-coded ordering and manual sorting of actions
	LEGACY;

	public static QueueType fromSetting(Object setting) {
		if ( setting != null ) {
			if ( setting instanceof QueueType queueType ) {
				return queueType;
			}
			return QueueType.fromSetting( setting.toString() );
		}

		return GRAPH;
	}

	public static QueueType fromSetting(String setting) {
		return switch ( setting.toLowerCase() ) {
			case "legacy" -> LEGACY;
			case "graph" -> GRAPH;
			default -> throw new IllegalArgumentException(
					"Unknown ActionQueue implementation: " + setting +
					". Valid values are 'graph' and 'legacy'."
			);
		};
	}
}

View on GitHub (pinned to fad1729dce)

Solutions

Set the property to exactly 'graph' or 'legacy' (any case).
Remove the property entirely - the default is GRAPH.
Check for trailing spaces, quotes, or environment-variable interpolation errors in the value.

Example fix

# before
hibernate.flush.queue.type=new
# after
hibernate.flush.queue.type=legacy

Defensive patterns

Strategy: validation

Validate before calling

// fail with a clear message before SessionFactory bootstrap
String v = settings.get("hibernate.flush.queue.type");
if (v != null && !Set.of("graph", "legacy").contains(v.toLowerCase(Locale.ROOT))) {
    throw new IllegalArgumentException("hibernate.flush.queue.type must be 'graph' or 'legacy', got: " + v);
}

Try / catch

try {
    sessionFactory = new Configuration().buildSessionFactory();
}
catch (IllegalArgumentException e) {
    if (e.getMessage() != null && e.getMessage().contains("Unknown ActionQueue implementation")) {
        // fix the hibernate.flush.queue.type value to 'graph' or 'legacy'
    }
    throw e;
}

Prevention

Validate the setting once in a config test or startup check instead of relying on bootstrap failure
Omit hibernate.flush.queue.type unless you specifically need the legacy queue
Beware yaml trailing whitespace and copy-pasted values from other Hibernate versions

When it happens

Trigger: Setting hibernate.flush.queue.type in persistence.xml, application.yaml/properties, or a programmatic settings map to a misspelled or outdated value such as 'new', 'default', or a value carried over from another Hibernate line.

Common situations: Copy-pasted configuration from an older Hibernate project or a blog post; trailing whitespace in yaml values; typo; settings files migrated between environments.

Related errors

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