hibernate/hibernate-orm · error · PathElementException

Could not resolve attribute '%s' of '%s'

Error message

Could not resolve attribute '%s' of '%s'

What it means

SqmPathSource.getSubPathSource(name) resolves the next segment of a query path (e.g. the 'name' in p.address.name) against a domain type. When findSubPathSource(name) returns null - the attribute simply does not exist on that type - Hibernate throws PathElementException (an IllegalArgumentException subclass) with the attribute and type names. This is the canonical 'unknown attribute in HQL/Criteria' error, raised while the SQM tree is being built, before SQL generation.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/query/sqm/spi/SqmPathSource.java:70

	 * @param includeSubtypes flag indicating whether to consider subtype attributes
	 * @return null if the subPathSource is not found
	 * @throws IllegalStateException to indicate that this source cannot be de-referenced
	 */
	default @Nullable SqmPathSource<?> findSubPathSource(String name, boolean includeSubtypes) {
		return findSubPathSource( name );
	}

	/**
	 * Find a {@link SqmPathSource} by name relative to this source.
	 *
	 * @param name the name of the path source to find
	 * @throws IllegalStateException to indicate that this source cannot be de-referenced
	 * @throws IllegalArgumentException if the subPathSource is not found
	 */
	default SqmPathSource<?> getSubPathSource(String name) {
		final SqmPathSource<?> subPathSource = findSubPathSource( name );
		if ( subPathSource == null ) {
			throw new PathElementException(
					String.format(
							Locale.ROOT,
							"Could not resolve attribute '%s' of '%s'",
							name,
							getExpressible().getTypeName()
					)
			);
		}
		return subPathSource;
	}

	/**
	 * Find a {@link SqmPathSource} by name relative to this source. If {@code subtypes} is set
	 * to {@code true} and this path source is polymorphic, also try finding subtype attributes.
	 *
	 * @param name the name of the path source to find
	 * @param subtypes flag indicating whether to consider subtype attributes
	 * @throws IllegalStateException to indicate that this source cannot be de-referenced

View on GitHub (pinned to fad1729dce)

Solutions

  1. Fix the path segment to the exact Java attribute/metadata name (check @AttributeOverride/@Column name and the field name)
  2. For dynamic names, validate against the metamodel first: check that entityManager.getMetamodel().entity(Person.class).getAttributes() contains the name
  3. If the attribute lives on a subtype, treat or join the subtype first (TREAT(p AS Sub).attr) or query the subtype entity
  4. If the attribute is on an embeddable, spell the full path p.embedded.field rather than jumping levels
  5. After renaming fields, grep all HQL strings and criteria get("...") literals for the old name

Example fix

// before
List<Person> r = session.createQuery("select p.naame from Person p", Object.class).list();
// after
List<Person> r = session.createQuery("select p.name from Person p", Object.class).list();
Defensive patterns

Strategy: validation

Validate before calling

// Validate a dynamic attribute name before using it
boolean exists = em.getMetamodel()
        .entity(Person.class)
        .getAttributes().stream()
        .anyMatch(a -> a.getName().equals(requestedName));
if (!exists) throw new IllegalArgumentException("Unknown attribute " + requestedName);

Type guard

static boolean isKnownAttribute(EntityManager em, Class<?> entity, String name) {
    try { em.getMetamodel().entity(entity).getAttribute(name); return true; }
    catch (IllegalArgumentException e) { return false; }
}

Try / catch

catch (PathElementException e) { /* message contains 'Could not resolve attribute' - log with the failing query and rethrow as 400 to caller */ }

Prevention

When it happens

Trigger: HQL with a misspelled or non-existent attribute: 'select p.naame from Person p'; Criteria root.get("naame"); referencing a field that exists only in a different entity; using a getter-derived name (getUserName -> 'userName') when the mapped column/attribute is named differently (e.g. 'user_name' or an explicit @AttributeOverride); referencing a subtype attribute on a supertype path without treat.

Common situations: Renaming an entity field without updating all queries (HQL strings are not checked by the compiler); dynamic/sort-parameter queries where a web request supplies the attribute name; switching naming strategies so implicit names change; expecting a DB column name instead of the Java attribute name in the path.

Related errors

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