hibernate/hibernate-orm · error · IllegalArgumentException

Unknown RepresentationMode

Error message

Unknown RepresentationMode

What it means

RepresentationMode.fromExternalName converts the string used in mappings/configuration into the POJO or MAP (dynamic-map) representation enum. Null yields POJO; recognized names are "pojo", "dynamic-map" and "map". Any other string falls through the switch and raises IllegalArgumentException("Unknown RepresentationMode"), surfacing at mapping parse/boot time.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/metamodel/RepresentationMode.java:33

 */
public enum RepresentationMode {
	POJO,
	MAP;

	public String getExternalName() {
		return switch ( this ) {
			case POJO -> "pojo";
			case MAP -> "dynamic-map";
		};
	}

	public static RepresentationMode fromExternalName(String externalName) {
		return externalName == null
				? POJO
				: switch ( externalName.toLowerCase( Locale.ROOT ) ) {
					case "pojo" -> POJO;
					case "dynamic-map", "map" -> MAP;
					default -> throw new IllegalArgumentException( "Unknown RepresentationMode" );
				};
	}
}

View on GitHub (pinned to fad1729dce)

Solutions

1. Set the attribute to a supported value: representation="pojo" or representation="dynamic-map" (legacy alias "map" also accepted).
2. Remove the obsolete dom4j representation entirely — it is unsupported; map XML payloads as basic types instead.
3. If the value comes from user config, validate it against {"pojo","dynamic-map","map"} before bootstrapping and fail with a helpful message.
4. Search the project for representation= / entity-mode= to catch all occurrences.

Example fix

<!-- before -->
<hibernate-mapping>
  <class entity-name="Item" representation="dom4j">...</class>
</hibernate-mapping>

<!-- after -->
<hibernate-mapping>
  <class entity-name="Item" representation="dynamic-map">...</class>
</hibernate-mapping>

Set<String> VALID = Set.of("pojo", "dynamic-map", "map");
String mode = config.get("hibernate.entity.mode");
if (mode != null && !VALID.contains(mode.toLowerCase(Locale.ROOT))) {
    throw new IllegalArgumentException("representation must be one of " + VALID + ": " + mode);
}

static boolean isValidRepresentationName(String name) {
    return name == null || Set.of("pojo", "dynamic-map", "map").contains(name.toLowerCase(Locale.ROOT));
}

When it happens

Trigger: hbm.xml declaring an invalid representation/entity-mode value (e.g. representation="dom4j" or representation="dynamicMap" instead of "dynamic-map"), parsed through RepresentationModeConverter; programmatic callers passing arbitrary user-supplied strings to RepresentationMode.fromExternalName.

Common situations: Legacy Hibernate 3 configurations using entity-mode="dom4j" (removed after Hibernate 5); typos like "dynamic_map"/"map-based"/"pojos" in hand-edited XML; config generated by templates with the wrong casing/separator; upgrading old projects whose hbm.xml still carries stale entity-mode attributes.

Related errors

• The {storageEngine} storage engine is not supported
• Informix only supports the case insensitive flag 'i' as lite
• Audit graph mutation plan used with non-graph action queue
• Audit graph mutation plan used with non-graph action queue
• Unknown ActionQueue implementation: %s. Valid values are 'gr

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