What causes "Unable to resolve property: {propertyName}" in hibernate/hibernate-orm?

Verify the name against persister.getPropertyNames() (or the JPA metamodel attributes) and fix the caller

hibernate/hibernate-orm · error · HibernateException

Unable to resolve property: {propertyName}

Error message

Unable to resolve property: {propertyName}

What it means

BaseEntityPersister.getPropertyIndex translates a property name to its positional index via the persister's precomputed propertyIndexes map and throws HibernateException('Unable to resolve property: X') on a miss. The map holds this persister's mapped property names, so the supplied name must exactly match a mapped property — not a DB column name, and not a name registered under a different access strategy.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/persister/entity/BaseEntityPersister.java:760

		return identifierAssignedByInsert;
	}

	protected Generator getIdentifierGenerator() {
		return identifierGenerator;
	}

	public int getPropertySpan() {
		return propertySpan;
	}

	public int getVersionPropertyIndex() {
		return versionPropertyIndex;
	}

	public int getPropertyIndex(String propertyName) {
		final Integer index = getPropertyIndexOrNull( propertyName );
		if ( index == null ) {
			throw new HibernateException( "Unable to resolve property: " + propertyName );
		}
		return index;
	}

	public Integer getPropertyIndexOrNull(String propertyName) {
		return propertyIndexes.get( propertyName );
	}

	public boolean hasCollections() {
		return hasCollections;
	}

	public boolean hasOwnedCollections() {
		return hasOwnedCollections;
	}

	public boolean hasMutableProperties() {
		return !mutablePropertiesIndexes.isEmpty();

View on GitHub (pinned to fad1729dce)

Solutions

Verify the name against persister.getPropertyNames() (or the JPA metamodel attributes) and fix the caller
Probe with getPropertyIndexOrNull(name) and handle null instead of calling getPropertyIndex directly
If the property lives on a subclass, resolve against the subclass persister, not the root

Example fix

// before
int idx = persister.getPropertyIndex("emial"); // typo -> HibernateException

// after
Integer idx = persister.getPropertyIndexOrNull(name);
if ( idx == null ) {
    throw new IllegalArgumentException(
        "Unknown property '" + name + "'; valid: "
        + List.of( persister.getPropertyNames() ) );
}

Defensive patterns

Strategy: validation

Validate before calling

Integer idx = persister.getPropertyIndexOrNull(propertyName);
if ( idx == null ) {
    throw new IllegalArgumentException(
        "Unknown property '" + propertyName + "'; valid names: "
        + java.util.List.of(persister.getPropertyNames()));
}

Try / catch

try {
    int idx = persister.getPropertyIndex(name);
}
catch ( org.hibernate.HibernateException e ) {
    // 'Unable to resolve property: <name>' -> surface valid names to the caller
    throw new IllegalArgumentException(
        e.getMessage() + "; valid: " + java.util.List.of(persister.getPropertyNames()), e);
}

Prevention

Derive property names from the JPA metamodel instead of hand-typed strings in configuration
Log persister.getPropertyNames() once at startup so mismatches are easy to diff
Remember property names, not column names, are required — and subclass properties may not resolve on the root persister

When it happens

Trigger: Calling persister.getPropertyIndex(name) with a misspelled name, a column name, a subclass-only property against the root persister, or a name that differs due to field-vs-property access; internal callers include unique-key/natural-id resolution and snapshot handling that take property names from configuration.

Common situations: Renaming a field without updating reflection/config-driven callers; passing column names from external configuration; property-ref style lookups where the configured name drifted from the mapped property; annotation vs XML naming mismatches.

Related errors

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