hibernate/hibernate-orm · error · MappingException

Unable to find NaturalIdClass accessor for natural id attrib

Error message

Unable to find NaturalIdClass accessor for natural id attribute: %s

What it means

Error "Unable to find NaturalIdClass accessor for natural id attribute: %s" thrown in hibernate/hibernate-orm.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/metamodel/mapping/internal/CompoundNaturalIdMapping.java:854

				return new GetterMethodImpl( naturalIdClass, keyName, component.getAccessor() );
			}
		}

		// next look for a getter method
		final var getterMethod = getterMethodAccess.apply( keyName );
		if ( getterMethod != null ) {
			return new GetterMethodImpl( naturalIdClass, keyName, getterMethod );
		}

		// lastly, look for a field
		try {
			return new GetterFieldImpl( naturalIdClass, keyName,
					naturalIdClass.getDeclaredField( keyName ) );
		}
		catch (NoSuchFieldException ignore) {
		}

		throw new MappingException( "Unable to find NaturalIdClass accessor for natural id attribute: " + keyName );
	}

	private static <T> Map<String, Method> extractGetterMethods(Class<T> naturalIdClass) {
		final Map<String, Method> result = new HashMap<>();
		for ( var declaredMethod : naturalIdClass.getDeclaredMethods() ) {
			if ( declaredMethod.getParameterCount() == 0
				&& declaredMethod.getReturnType() != void.class
				&& !isStatic( declaredMethod.getModifiers() ) ) {
				var methodName = declaredMethod.getName();
				if ( methodName.startsWith( "is" ) ) {
					result.put( decapitalize( methodName.substring( 2 ) ),
							declaredMethod );
				}
				else if ( methodName.startsWith( "get" ) ) {
					result.put( decapitalize( methodName.substring( 3 ) ),
							declaredMethod );
				}
			}

View on GitHub (pinned to fad1729dce)

Solutions

1. Ensure the NaturalIdClass has a readable property for every natural-id attribute of the entity.
2. Check that the NaturalIdClass attribute names match the entity's natural-id attribute names.

When it happens

Trigger: Thrown when a compound natural id uses a NaturalIdClass but no accessor can be found for one of its attributes.

Common situations: See trigger scenarios.

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