hibernate/hibernate-orm · error · IllegalStateException

@Convert placed on @Embeddable must define attributeName

Error message

@Convert placed on @Embeddable must define attributeName

What it means

Error "@Convert placed on @Embeddable must define attributeName" thrown in hibernate/hibernate-orm.

Source

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

		// 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 );
		} );
	}

	private Map<String,AttributeConversionInfo> processAttributeConversions(TypeDetails embeddableTypeDetails) {
		final Map<String,AttributeConversionInfo> infoMap = new HashMap<>();
		processAttributeConversions( embeddableTypeDetails, infoMap );
		return infoMap;
	}

	@Override
	protected String normalizeCompositePath(String attributeName) {
		return embeddedAttributeName + '.' + attributeName;
	}

	@Override
	protected String normalizeCompositePathForLogging(String attributeName) {

View on GitHub (pinned to fad1729dce)

Solutions

1. Set attributeName on the @Convert annotation placed on the @Embeddable class.

When it happens

Trigger: A @Convert / AttributeConverter declaration is missing required information or applies to a target that forbids conversion.

Common situations: @Convert without attributeName on a class-level or embedded target, or a converter clashing with a mapping annotation like @Enumerated/@Temporal that requires disableConversion=true.

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