hibernate/hibernate-orm · error · IllegalStateException

Could not determine how to apply @Convert(attributeName='%s'

Error message

Could not determine how to apply @Convert(attributeName='%s') to collection [%s]

What it means

Error "Could not determine how to apply @Convert(attributeName='%s') to collection [%s]" thrown in hibernate/hibernate-orm.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/boot/model/internal/CollectionPropertyHolder.java:163

			}
			else if ( canKeyBeConverted ) {
				keyPath = removePrefix( attributeName, "key", attributeName );
				elementPath = null;
			}
			else {
				keyPath = null;
				elementPath = removePrefix( attributeName, "value", attributeName );
			}

			if ( keyPath != null ) {
				keyAttributeConversionInfoMap.put( keyPath, info );
			}
			else if ( elementPath != null ) {
				elementAttributeConversionInfoMap.put( elementPath, info );
			}
			else {
				// specified attributeName needs to have 'key.' or 'value.' prefix
				throw new IllegalStateException(
						String.format(
								Locale.ROOT,
								"Could not determine how to apply @Convert(attributeName='%s') to collection [%s]",
								attributeName,
								collection.getRole()
						)
				);
			}
		}
	}

	private void throwMissingAttributeName() {
		throw new IllegalStateException( "'@Convert' annotation for map [" + collection.getRole()
									+ "] must specify 'attributeName=\"key\"' or 'attributeName=\"value\"'" );
	}

	private static void logSpecNoncompliance(String attributeName, String role) {
		final boolean specCompliant = isNotEmpty( attributeName )

View on GitHub (pinned to fad1729dce)

Solutions

1. Correct the attributeName in @Convert to match an element, key, or value path valid for the collection.
2. Or move the @Convert annotation to the owning attribute it applies to.

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/fe9741b3c04713ce. Report an issue: GitHub.