hibernate/hibernate-orm · error · IllegalStateException

Convert placed on Embedded attribute must define (sub)attrib

Error message

Convert placed on Embedded attribute must define (sub)attributeName

What it means

Error "Convert placed on Embedded attribute must define (sub)attributeName" thrown in hibernate/hibernate-orm.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/boot/model/internal/ComponentPropertyHolder.java:204

	 *
	 * @param embeddedMemberDetails The property that is the composite being described by this ComponentPropertyHolder
	 */
	private Map<String,AttributeConversionInfo> processAttributeConversions(MemberDetails embeddedMemberDetails) {
		final Map<String,AttributeConversionInfo> infoMap = new HashMap<>();

		final var embeddableTypeDetails = embeddedMemberDetails.getType();

		// as a baseline, we want to apply conversions from the Embeddable and then overlay conversions
		// from the Embedded

		// first apply conversions from the Embeddable...
		processAttributeConversions( embeddableTypeDetails, infoMap );

		// then we can overlay any conversions from the Embedded attribute
		embeddedMemberDetails.forEachAnnotationUsage( Convert.class, getSourceModelContext(), (usage) -> {
			final var info = new AttributeConversionInfo( usage, embeddedMemberDetails );
			if ( isEmpty( info.getAttributeName() ) ) {
				throw new IllegalStateException( "Convert placed on Embedded attribute must define (sub)attributeName" );
			}
			infoMap.put( info.getAttributeName(), info );
		} );

		return infoMap;
	}

	private void processAttributeConversions(TypeDetails embeddableTypeDetails, Map<String, AttributeConversionInfo> infoMap) {
		final var embeddableClassDetails = embeddableTypeDetails.determineRawClass();
		embeddableClassDetails.forEachAnnotationUsage( Convert.class, getSourceModelContext(), (usage) -> {
			final var info = new AttributeConversionInfo( usage, embeddableClassDetails );
			if ( isEmpty( info.getAttributeName() ) ) {
				throw new IllegalStateException( "@Convert placed on @Embeddable must define attributeName" );
			}
			infoMap.put( info.getAttributeName(), info );
		} );
	}

View on GitHub (pinned to fad1729dce)

Solutions

1. Set attributeName on the @Convert annotation to the (sub)attribute of the embedded attribute it applies to.

When it happens

Trigger: A @Convert annotation lacks the attributeName needed to identify the converted attribute.

Common situations: @Convert on an @Embeddable or @Embedded attribute without (sub)attributeName, so the converter target is ambiguous.

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