hibernate/hibernate-orm · error · IllegalStateException

'@Convert' annotation for map [<role>] must specify 'attribu

Error message

'@Convert' annotation for map [<role>] must specify 'attributeName="key"' or 'attributeName="value"'

What it means

Error "'@Convert' annotation for map [<role>] must specify 'attributeName="key"' or 'attributeName="value"'" thrown in hibernate/hibernate-orm.

Source

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

			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 )
				&& (attributeName.startsWith( "key" ) || attributeName.startsWith( "value" ) );
		if ( !specCompliant ) {
			BOOT_LOGGER.nonCompliantMapConversion( role );
		}
	}

	/**
	 * Check if path has the given prefix and remove it.
	 *
	 * @param path Path.
	 * @param prefix Prefix.
	 * @return Path without prefix, or null, if path did not have the prefix.
	 */

View on GitHub (pinned to fad1729dce)

Solutions

1. Set @Convert(attributeName="key") or @Convert(attributeName="value") for the map mapping.

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