hibernate/hibernate-orm · error · HibernateException

Unrecognized graph_parser_mode value : " + graphParserMode +

Error message

Unrecognized graph_parser_mode value : " + graphParserMode + ".  Supported values include 'modern' and 'legacy'.

What it means

GraphParserMode.interpret parses the 'hibernate.graph_parser_mode' setting: null returns LEGACY (default), a GraphParserMode instance is passed through, and a String is matched case-insensitively against MODERN/LEGACY. Any other object or unrecognized string throws HibernateException listing the supported values 'modern' and 'legacy'. This controls the syntax accepted by EntityGraph parsing (e.g. attribute:SubType(...) vs legacy attribute(SubType: ...)).

Source

Thrown at hibernate-core/src/main/java/org/hibernate/GraphParserMode.java:57

	 * @param graphParserMode configured {@link GraphParserMode} representation
	 *
	 * @return associated {@link GraphParserMode} object
	 */
	public static GraphParserMode interpret(Object graphParserMode) {
		if ( graphParserMode == null ) {
			return LEGACY;
		}
		else if ( graphParserMode instanceof GraphParserMode mode ) {
			return mode;
		}
		else if ( graphParserMode instanceof String string ) {
			for ( GraphParserMode value : values() ) {
				if ( value.name().equalsIgnoreCase( string ) ) {
					return value;
				}
			}
		}
		throw new HibernateException(
				"Unrecognized graph_parser_mode value : " + graphParserMode
						+ ".  Supported values include 'modern' and 'legacy'."
		);
	}
}

View on GitHub (pinned to fad1729dce)

Solutions

1. Set the value to 'modern' or 'legacy' (case-insensitive).
2. Remove the property entirely - a missing/null setting defaults to LEGACY.
3. If the value comes from an external source, validate it is one of the two accepted strings before startup.

Example fix

<!-- before -->
<property name="hibernate.graph_parser_mode" value="new"/>

<!-- after -->
<property name="hibernate.graph_parser_mode" value="modern"/>

static String normalizeGraphParserMode(String raw) {
    if (raw == null) return null; // defaults to LEGACY
    for (GraphParserMode m : GraphParserMode.values()) {
        if (m.name().equalsIgnoreCase(raw.trim())) return m.getConfigValue();
    }
    throw new IllegalArgumentException("graph_parser_mode must be 'modern' or 'legacy', got: " + raw);
}

try {
    SessionFactory sf = cfg.buildSessionFactory();
} catch (HibernateException e) {
    if (e.getMessage().contains("graph_parser_mode")) {
        cfg.getStandardServiceRegistryBuilder().clearSettings(); // drop bad value, rebuild with default
    }
    throw e;
}

When it happens

Trigger: Setting the property 'hibernate.graph_parser_mode' in persistence.xml/hibernate.properties to anything other than modern/legacy - e.g. 'new', 'default', 'on', or a non-string object - then building the SessionFactory (SessionFactoryOptionsBuilder reads the setting).

Common situations: Upgrading Hibernate 6.x to 7.x and guessing at the new setting's value; YAML/env-injected config with a stray boolean or typo; documentation drift between versions using different property names/values.

Related errors

• The {storageEngine} storage engine is not supported
• Could not instantiate event listener '{}'
• Unable to instantiate StatementObserver - {}
• The 'root' parameter of the @NamedEntityGraph should be pass
• The 'root' parameter of the @NamedEntityGraph annotation mus

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