hibernate/hibernate-orm · error · MappingException

component type [{}] specifies {} properties for the instanti

Error message

component type [{}] specifies {} properties for the instantiator but has {} properties

What it means

Component#isValid rejects an embeddable whose @Instantiator-annotated constructor declares fewer parameters than the embeddable has persistent properties. Hibernate (6.6+) requires the chosen instantiator to cover every property so hydration can never leave a field unset.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/mapping/Component.java:820

			if ( generator instanceof Configurable configurable ) {
				configurable.initialize( context );
			}
		}
	}

	public void prepareForMappingModel() {
		// This call will initialize the type properly
		getType();
	}

	@Override
	public boolean isValid(MappingContext mappingContext) throws MappingException {
		if ( !super.isValid( mappingContext ) ) {
			return false;
		}
		if ( instantiatorPropertyNames != null ) {
			if ( instantiatorPropertyNames.length < properties.size() ) {
				throw new MappingException( "component type [" + componentClassName + "] specifies " + instantiatorPropertyNames.length + " properties for the instantiator but has " + properties.size() + " properties" );
			}
			final HashSet<String> assignedPropertyNames = CollectionHelper.setOfSize( properties.size() );
			for ( String instantiatorPropertyName : instantiatorPropertyNames ) {
				if ( getProperty( instantiatorPropertyName ) == null ) {
					throw new MappingException( "could not find property [" + instantiatorPropertyName + "] defined in the @Instantiator withing component [" + componentClassName + "]" );
				}
				assignedPropertyNames.add( instantiatorPropertyName );
			}
			if ( assignedPropertyNames.size() != properties.size() ) {
				final ArrayList<String> missingProperties = new ArrayList<>();
				for ( var property : properties ) {
					final String propertyName = property.getName();
					if ( !assignedPropertyNames.contains( propertyName ) ) {
						missingProperties.add( propertyName );
					}
				}
				throw new MappingException( "component type [" + componentClassName + "] has " + properties.size() + " properties but the instantiator only assigns " + assignedPropertyNames.size() + " properties. missing properties: " + missingProperties );
			}

View on GitHub (pinned to fad1729dce)

Solutions

Extend the annotated constructor so it accepts every persistent property of the embeddable.
Or remove @Instantiator so Hibernate selects the canonical all-args constructor itself.
For shapes that cannot be 1:1, register a dedicated @EmbeddableInstantiator implementation instead of annotating a constructor.

Example fix

// before
@Embeddable
public class Name {
    private String first;
    private String last;

    @Instantiator
    Name(String first) { this.first = first; }
}

// after
@Embeddable
public class Name {
    private String first;
    private String last;

    @Instantiator
    Name(String first, String last) {
        this.first = first;
        this.last = last;
    }
}

Defensive patterns

Strategy: validation

Validate before calling

static boolean coversAllProperties(Class<?> embeddable, Constructor<?> ctor) {
    long fields = Arrays.stream(embeddable.getDeclaredFields())
            .filter(f -> !Modifier.isStatic(f.getModifiers()))
            .count();
    return ctor.getParameterCount() >= fields;
}

Prevention

Prefer records or canonical all-args constructors for embeddables - coverage is automatic.
When adding a field to an embeddable with an @Instantiator constructor, update the constructor in the same commit.
Run Metadata building in unit tests so isValid failures hit CI, not production.

When it happens

Trigger: A hand-written partial constructor is marked @Instantiator while the class has more fields; a new field was added to the embeddable without updating the annotated constructor; a canonical constructor was replaced by a convenience constructor.

Common situations: Evolving @Embeddable/@EmbeddedId classes that use explicit @Instantiator; porting classes with overloaded constructors to Hibernate 6.6; replacing records with plain classes that have partial constructors.

Related errors

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