hibernate/hibernate-orm · error · IllegalArgumentException

Unrecognized value type Java-type [" + valueDomainType.getTy

Error message

Unrecognized value type Java-type [" + valueDomainType.getTypeName() + "] for plural attribute value

What it means

SqmMappingModelHelper.valuePathSource builds an SqmPathSource for the VALUE of a plural attribute by switching on the element's domain type: embedded, entity, and mapped-superclass types are handled explicitly, and anything else falls into the else branch that throws IllegalArgumentException. Reaching it means the collection's target/element type resolved to an SqmDomainType Hibernate does not recognize as a path-source-capable value type.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/query/sqm/internal/SqmMappingModelHelper.java:148

			return new EntitySqmPathSource<>(
					name,
					pathModel,
					entityDomainType,
					jpaBindableType,
					isGeneric
			);
		}
		else if ( valueDomainType instanceof SqmMappedSuperclassDomainType<J> mappedSuperclassDomainType ) {
			return new MappedSuperclassSqmPathSource<>(
					name,
					pathModel,
					mappedSuperclassDomainType,
					jpaBindableType,
					isGeneric
			);
		}
		else {
			throw new IllegalArgumentException(
					"Unrecognized value type Java-type [" + valueDomainType.getTypeName() + "] for plural attribute value"
			);
		}
	}

	public static MappingModelExpressible<?> resolveMappingModelExpressible(
			SqmTypedNode<?> sqmNode,
			MappingMetamodel domainModel,
			Function<NavigablePath,TableGroup> tableGroupLocator) {
		if ( sqmNode instanceof SqmPath ) {
			return resolveSqmPath( (SqmPath<?>) sqmNode, domainModel, tableGroupLocator );
		}

		final SqmExpressible<?> nodeType = sqmNode.getNodeType();
		if ( nodeType instanceof BasicType ) {
			return (BasicType<?>) nodeType;
		}

View on GitHub (pinned to fad1729dce)

Solutions

Fix the mapping: @ElementCollection targets must be basic or embeddable types, @OneToMany/@ManyToMany targetEntity must be a managed entity — verify targetClass/targetEntity actually names an @Entity/@Embeddable or a supported basic type.
If you navigate the VALUE side in criteria/HQL (e.g. value(...) on a map), make sure the element is an embeddable or entity; for basic elements query the collection join directly instead of by value-path.
If the mapping follows the spec and still fails, capture the valueDomainType (name in the message) and report a Hibernate JIRA with a reproducer — the else branch indicates an unhandled mapping-model type.

Example fix

// before
@OneToMany(targetEntity = OrderStatus.class /* not an @Entity */) // element resolves to unrecognized type
private List<OrderStatus> statuses;
// criteria navigation triggers: Unrecognized value type Java-type [...]

// after
@ElementCollection
@Enumerated(EnumType.STRING)
private List<OrderStatus> statuses; // basic enum element: query via join, no entity targetClass

Defensive patterns

Strategy: try-catch

Validate before calling

// Validate plural-attribute targets at startup instead of at query time
for (ManagedType<?> t : emf.getMetamodel().getManagedTypes()) {
    for (Attribute<?, ?> a : t.getAttributes()) {
        if (a.isCollection()) {
            Type<?> elt = ((PluralAttribute<?, ?, ?>) a).getElementType();
            // element must be basic, embeddable, or entity — flag anything you expect to be queryable by value-path
        }
    }
}

Type guard

static boolean valuePathCapable(PluralAttribute<?, ?, ?> pa) {
    Type.PersistenceType pt = pa.getElementType().getPersistenceType();
    return pt == Type.PersistenceType.EMBEDDABLE || pt == Type.PersistenceType.ENTITY;
}

Try / catch

try {
    criteriaNavigation(); // e.g. value-path over a plural attribute
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("Unrecognized value type")) { /* fix element mapping; not a runtime-recoverable error */ throw e; }
    throw e;
}

Prevention

Declare @ElementCollection only over basic/embeddable elements and collection relations only over entity targets.
Verify targetClass/targetEntity values resolve to actual @Entity/@Embeddable classes in a startup smoke test.
After a Hibernate upgrade, run your full criteria query suite — mapping-model branches like this change between versions.

When it happens

Trigger: An @ElementCollection (or collection-valued attribute) whose targetEntity/target class resolves to a basic or exotic user type rather than an embeddable/entity; custom collection mappings with a custom BasicType or a user-defined domain type as element; mappings that worked on one Hibernate version and hit an unhandled branch after an upgrade changed type resolution.

Common situations: Upgrading Hibernate (6.x/7.x) where collection element type resolution changed; @ElementCollection over an enum or custom BasicType combined with criteria value-path navigation (value() on plural paths); misdeclared targetClass on @OneToMany/@ManyToMany pointing at a non-entity class.

Related errors

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