Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Databases and Redis

Spring Data JPA rejects the @Query on one repository method

ErrorValidation failed for query for method

Short answer

The message names the repository method and the query string that Spring Data could not accept. A JPQL query must use entity names and attribute names, not table and column names. The three real causes are SQL names inside JPQL, native SQL without nativeQuery = true, and an entity renamed with @Entity(name = ...).

  • Applies to Spring Boot 3.4, Spring Data JPA 3.4, Hibernate 6.6, Java 21
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Read the method name and the query in the message, then compare each word after from, join and where with your entity class: is it a class or field name, or a table or column name?

    grep -n 'Validation failed for query' app.log | head -n 3
    grep -rn '@Query' src/main/java
  2. 2Match what you see, then jump to its fix

    1. 1The query reads like SQL: select * from users where email_address = ?1Table or column names were used in a JPQL queryFix
    2. 2The query uses database features JPQL does not have, or selects with * from a tableA native SQL query is missing nativeQuery = trueFix
    3. 3The class exists, but the query fails when it is written with the class nameThe entity name is not the class nameFix

What does the error look like?

  • Validation failed for query for method
  • Caused by: java.lang.IllegalArgumentException: Validation failed for query for method public abstract ...

Cause 1 of 3

Table or column names were used in a JPQL query

1Check

JPQL is the default for @Query, and it refers to entity names and property paths, such as select u from User u where u.emailAddress = ?1. Native SQL is the one that uses table and column names.

grep -rn '@Query' src/main/java | grep -i 'from'
grep -rn '@Column\|@Table' src/main/java | head

2Fix

Rewrite the query with the entity name and its Java field names.

@Query("select u from User u where u.emailAddress = ?1")
User findByEmailAddress(String emailAddress);

3Verify

Start the application context, or run the repository test for that method.

./mvnw -q test -Dtest=UserRepositoryTest

Confirmed by docs.spring.io

Did this fix it?

Cause 2 of 3

A native SQL query is missing nativeQuery = true

1Check

Native SQL needs nativeQuery = true on @Query, or the @NativeQuery annotation. Without it the text is parsed as JPQL.

grep -rn 'SELECT \*\|select \*' src/main/java

2Fix

Mark the query as native and keep table and column names in it.

@Query(value = "SELECT * FROM USERS WHERE EMAIL_ADDRESS = ?1", nativeQuery = true)
User findByEmailAddress(String emailAddress);

3Verify

Run the repository test again; the method is accepted.

./mvnw -q test -Dtest=UserRepositoryTest

Confirmed by docs.spring.io

Did this fix it?

Cause 3 of 3

The entity name is not the class name

1Check

The entity name used in JPQL is the name property of @Entity if it is set, and the simple class name otherwise. After a rename such as @Entity(name = "MyUser"), queries that still say User no longer match.

grep -rn '@Entity' src/main/java

2Fix

Use the entity name in the query, or avoid hard-coding it with the #{#entityName} expression.

@Query("select u from #{#entityName} u where u.lastname = ?1")
List<User> findByLastname(String lastname);

3Verify

Run the repository test for that method.

./mvnw -q test -Dtest=UserRepositoryTest

Confirmed by docs.spring.io

Did this fix it?

How do I stop it coming back?

  • Cover every @Query method with at least one repository test; a bad query then fails in CI.
  • Write JPQL with entity and field names, and keep native SQL in methods clearly marked nativeQuery.
  • Prefer #{#entityName} in generic repositories instead of a hard-coded class name.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.