hibernate/hibernate-orm · error · HibernateException

Unrecognized flush mode : ${name}

Error message

Unrecognized flush mode : ${name}

What it means

FlushModeMarshalling.fromXml accepts exactly three tokens case-insensitively: 'never' (mapped to FlushMode.MANUAL), 'auto', and 'always'. Any other non-null string — including otherwise valid enum names like 'commit' or 'manual' — throws HibernateException('Unrecognized flush mode : name'). The comment in code notes this should never occur in schema-valid documents, because the XSD restricts the attribute values.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/boot/jaxb/mapping/internal/FlushModeMarshalling.java:43

		// Also, we want to map "never"->MANUAL (rather than NEVER)
		if ( name == null ) {
			return null;
		}

		if ( "never".equalsIgnoreCase( name ) ) {
			return FlushMode.MANUAL;
		}
		else if ( "auto".equalsIgnoreCase( name ) ) {
			return FlushMode.AUTO;
		}
		else if ( "always".equalsIgnoreCase( name ) ) {
			return FlushMode.ALWAYS;
		}

		// if the incoming value was not null *and* was not one of the pre-defined
		// values, we need to throw an exception.  This *should never happen if the
		// document we are processing conforms to the schema...
		throw new HibernateException( "Unrecognized flush mode : " + name );
	}

	public static String toXml(FlushMode mode) {
		if ( mode == null ) {
			return null;
		}

		// conversely, we want to map MANUAL -> "never" here
		if ( mode == FlushMode.MANUAL ) {
			return "never";
		}

		// todo : what to do if the incoming value does not conform to allowed values?
		// for now, we simply don't deal with that (we write it out).

		return mode.name().toLowerCase( Locale.ENGLISH );
	}
}

View on GitHub (pinned to fad1729dce)

Solutions

1. Change the XML value to one of 'never', 'auto', or 'always' (these are the only XML-legal tokens)
2. If you need COMMIT semantics, configure the flush mode programmatically on the Session/Query instead of in XML
3. Validate all mapping documents against Hibernate's bundled XSD in CI so out-of-vocabulary values fail early with a precise location

Example fix

<!-- before -->
<query name="Item.bySku" flush-mode="commit">...</query>

<!-- after -->
<query name="Item.bySku" flush-mode="always">...</query>

private static final Set<String> XML_FLUSH_MODES = Set.of("never", "auto", "always");
String value = attrValue.toLowerCase(java.util.Locale.ROOT);
if (!XML_FLUSH_MODES.contains(value)) {
    throw new IllegalArgumentException("flush-mode must be one of " + XML_FLUSH_MODES + ": " + value);
}

catch (HibernateException e) {
    if (e.getMessage() != null && e.getMessage().startsWith("Unrecognized flush mode")) {
        throw new IllegalArgumentException("XML flush-mode must be never|auto|always", e);
    }
    throw e;
}

When it happens

Trigger: A flush-mode attribute in an hbm.xml (e.g. <query flush-mode="...">) or mapping document containing a token outside {never, auto, always}: 'commit', 'manual', 'automatic', or a typo — possible when schema validation was skipped, the document was hand-built, or a custom XSD relaxed the enumeration.

Common situations: Developers copying FlushMode.COMMIT's enum name into XML; tooling generating mappings from annotations without mapping enum names to the XML vocabulary; hand-written XML that was never schema-validated.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Unable to perform unmarshalling at line number {} and column
• Could not instantiate named strategy class [%s]
• Could not locate root element
• Mapping (%s) not found : %s
• Could not parse mapping document: %s (%s)

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