hibernate/hibernate-orm · error · MappingException

mapped composite identifier must name component class to use

Error message

mapped composite identifier must name component class to use.

What it means

Error "mapped composite identifier must name component class to use." thrown in hibernate/hibernate-orm.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/boot/model/source/internal/hbm/EntityHierarchySourceImpl.java:106

					String.format(
							Locale.ROOT,
							"Entity [%s] did not define an identifier",
							rootEntitySource.getEntityNamingSource().getEntityName()
					),
					rootEntitySource.origin()
			);
		}

		if ( simpleId != null ) {
			return new IdentifierSourceSimpleImpl( rootEntitySource );
		}
		else {
			// if we get here, we should have a composite identifier.  Just need
			// to determine if it is aggregated, or non-aggregated...

			if ( compositeId.isMapped() ) {
				if ( StringHelper.isEmpty( compositeId.getClazz() ) ) {
					throw new MappingException(
							"mapped composite identifier must name component class to use.",
							rootEntitySource.origin()
					);
				}
			}

			if ( StringHelper.isEmpty( compositeId.getName() ) ) {
				if ( compositeId.isMapped() && StringHelper.isEmpty( compositeId.getClazz() ) ) {
					throw new MappingException(
							"mapped composite identifier must name component class to use.",
							rootEntitySource.origin()
					);
				}
				return new IdentifierSourceNonAggregatedCompositeImpl( rootEntitySource );
			}
			else {
				if ( compositeId.isMapped() ) {
					throw new MappingException(

View on GitHub (pinned to fad1729dce)

Solutions

1. Set the class attribute on <composite-id/> naming the embeddable/component class to use.

Example fix

Set the class attribute on <composite-id/> naming the embeddable/component class to use.

When it happens

Trigger: An hbm.xml / orm.xml mapping document violates a mapping rule during bootstrap.

Common situations: Legacy XML mappings with invalid combinations (column+formula, mixed inheritance, missing identifiers, bad extends references).

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