hibernate/hibernate-orm · error · MappingException

{} property '{}.{}' must be a basic attribute

Error message

{} property '{}.{}' must be a basic attribute

What it means

Error "{} property '{}.{}' must be a basic attribute" thrown in hibernate/hibernate-orm.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/boot/model/internal/AuditHelper.java:573

	 * Validate that a named property exists and is mapped as a {@link BasicValue}.
	 */
	private static Property requireBasicProperty(
			PersistentClass entityBinding,
			String propertyName,
			String annotationName) {
		final Property property;
		try {
			property = entityBinding.getProperty( propertyName );
		}
		catch (MappingException e) {
			throw new MappingException(
					annotationName + " member '" + propertyName
							+ "' is not mapped as a property on @Changelog '"
							+ entityBinding.getEntityName() + "'"
			);
		}
		if ( !( property.getValue() instanceof BasicValue ) ) {
			throw new MappingException(
					annotationName + " property '" + entityBinding.getEntityName()
							+ "." + propertyName + "' must be a basic attribute"
			);
		}
		return property;
	}

	/**
	 * Create an audit table for the given source table: copy columns,
	 * add the REV column, create the composite PK, and add the
	 * REV -> REVINFO FK (if a changelog entity is configured).
	 */
	private static Table createAuditTable(
			Table sourceTable,
			String csIdColumnName,
			Set<String> excludedColumns,
			@Nullable String schemaOverride,
			@Nullable String catalogOverride,

View on GitHub (pinned to fad1729dce)

Solutions

1. Change the property to a basic attribute type, or remove the annotation that requires a basic attribute.
2. If an association or embedded type is intended, use the mapping appropriate for that kind instead.

When it happens

Trigger: An Envers-style @Changelog member mapping is invalid (multiple annotated members, unmapped member, or non-basic attribute).

Common situations: Audited entities where the changelog class has more than one tracked member, references a property that is not mapped, or tracks a non-basic (association/embeddable) attribute.

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