hibernate/hibernate-orm · error · MappingException

Unable to resolve audit table mapping for %s

Error message

Unable to resolve audit table mapping for %s

What it means

EntityAuditSupport.resolveAuditTableIndex maps a mutating table name to its entry in auditTableMappings; entries can be null for tables excluded from auditing. MappingException 'Unable to resolve audit table mapping for <table>' means a mutation is being applied to a table that has no audit mapping - it is excluded (or unknown) while the mutation coordinator still needs to write audit data for it.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/persister/entity/mutation/EntityAuditSupport.java:608

				auditTableMapping.isCascadeDeleteEnabled(),
				tableMapping.getInsertDetails(),
				tableMapping.getUpdateDetails(),
				tableMapping.getDeleteDetails(),
				List.of(),
				List.of(),
				Map.of(),
				identifierTableDescriptor.keyDescriptor()
		);
	}

	private int resolveAuditTableIndex(String tableName) {
		for ( int i = 0; i < auditTableMappings.length; i++ ) {
			if ( auditTableMappings[i] != null
					&& auditTableMappings[i].getTableName().equals( tableName ) ) {
				return i;
			}
		}
		throw new MappingException( "Unable to resolve audit table mapping for " + tableName );
	}

	private boolean[] applyAuditMask(boolean[] propertyInclusions) {
		final boolean[] masked = propertyInclusions.clone();
		for ( int i = 0; i < masked.length; i++ ) {
			if ( !auditedPropertyMask[i] ) {
				masked[i] = false;
			}
		}
		return masked;
	}

	private static boolean isValueGenerated(Generator generator) {
		return generator != null
				&& generator.generatesOnInsert()
				&& generator.generatedOnExecution();
	}

View on GitHub (pinned to fad1729dce)

Solutions

1. Include every mutable table of the entity in the audit mapping
2. Or make the excluded table's attributes insertable=false/updatable=false so no mutation targets it
3. Re-generate or refresh the audit mapping after schema changes so table sets match
4. Add a boot-time consistency check comparing persister table names with audit-mapped table names

When it happens

Trigger: An entity with secondary tables whose audit mapping excludes one of them, while inserts/updates still write that table; a subclass table mutated when the audit mapping only covered the root; audit table names out of sync with entity table names after schema or mapping edits.

Common situations: Excluding audit coverage for a @SecondaryTable but leaving its attributes updatable; adding secondary or subclass tables after the audit mapping was defined; partial table renames between the entity mapping and the audit configuration.

Related errors

• Secondary table (<join/>) must explicitly name table or sub-
• Could not locate Table : " + name
• Could not locate secondary Table : " + name
• No audit mapping available for %s
• Secondary table '${explicitTableName}' for property '${prope

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