QueryDSL QClass Generated but Hibernate Fails to Recognize Entity in Spring Boot 3.2.3

When integrating QueryDSL with Hibernate in Spring Boot 3.2.3, developers sometimes stumble upon a tricky challenge: although the QueryDSL generated classes (often known as QClasses) appear correctly generated, Hibernate throws a confusing error during runtime. This mismatch between successfully generated QueryDSL classes and Hibernate’s entity recognition can leave developers scratching their heads.

A common scenario involves successfully generating a QClass, say QBandManagement, only to have Hibernate complain with an error message like this during application startup or query execution:

org.hibernate.query.sqm.UnknownEntityException: Could not resolve target entity 'BandManagement'

Even though your import statement is correctly set, typically something like:

import com.example.project.domain.QBandManagement;

The error persists. What’s going on here?

Understanding the Problem: Hibernate’s Entity Recognition vs. QueryDSL QClasses

At its core, this issue arises because Hibernate doesn’t recognize your entity even though QueryDSL has correctly generated its associated Q-Class. Simply put, QueryDSL and Hibernate interact differently. QueryDSL is a great tool for building dynamic, typesafe queries, generating helpful classes that represent your domain. On the other hand, Hibernate is specifically responsible for recognizing and mapping Java entities to database tables.

When Hibernate throws the UnknownEntityException, it means that it cannot locate or resolve your specified entity—for example, ‘BandManagement’. This may seem odd because your QueryDSL setup appears correct. However, the issue here generally boils down to either incorrect entity configuration or misalignment between Hibernate and QueryDSL configurations.

My Project Setup—Environment and Context

To provide some context, here’s the environment and setup involved:

• IDE: IntelliJ IDEA (latest stable release)
• Spring Boot version: 3.2.3 (latest stable as of now)
• QueryDSL version: 5.0.0
• Build Tool: Gradle

The typical structure of the Spring Boot project looks like this:

src
└── main
    ├── java
    │   └── com
    │       └── example
    │           └── project
    │               ├── Application.java
    │               └── domain
    │                   ├── BandManagement.java
    │                   └── QBandManagement.java (generated by QueryDSL)
    └── resources
        └── application.yml

The entity, BandManagement.java, resides within the domain package. Meanwhile, QueryDSL generates its corresponding QBandManagement.java class in the right package.

Why Is Hibernate Unable to Recognize the Entity?

The main reason Hibernate doesn’t recognize your entity BandManagement is typically related to one of these factors:

• The class is not annotated properly for Hibernate recognition (missing @Entity annotation or wrong import).
• Misconfigured QueryDSL apt plugin or its Gradle setup.
• The entity package location isn’t properly scanned by Spring Boot or Hibernate.

To pinpoint the problem, let’s first check the entity class:

@Entity
public class BandManagement {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    private String bandName;

    // getters and setters here
}

Notice the annotation @Entity from javax.persistence or jakarta.persistence. With Spring Boot 3.0+ and Hibernate 6, you must use jakarta.persistence instead of the older javax.* package.

If you’re mistakenly importing or mixing javax and jakarta source packages, Hibernate won’t recognize the entity at runtime, even though QueryDSL might still work fine.

What I’ve Already Tried—to No Avail

If you’re like many developers, you’ve probably got a build.gradle configuration similar to this for QueryDSL setup:

plugins {
    id 'org.springframework.boot' version '3.2.3'
    id 'io.spring.dependency-management' version '1.1.4'
    id 'java'
}

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-data-jpa'
    implementation 'com.querydsl:querydsl-jpa:5.0.0:jakarta'

    annotationProcessor 'com.querydsl:querydsl-apt:5.0.0:jakarta'
    annotationProcessor 'jakarta.persistence:jakarta.persistence-api:3.1.0'
    annotationProcessor 'jakarta.annotation:jakarta.annotation-api:2.1.1'
    runtimeOnly 'com.h2database:h2'
}

def queryDslDir = 'src/main/generated'

sourceSets {
    main.java.srcDirs += [ queryDslDir ]
}

tasks.withType(JavaCompile).configureEach {
    options.generatedSourceOutputDirectory = file(queryDslDir)
}

clean.doLast {
    file(queryDslDir).deleteDir()
}

This setup correctly generates QClasses—but Hibernate still isn’t happy.

In-depth Analysis—Why is this Happening?

QueryDSL is purely a query library—it doesn’t verify or directly interact with Hibernate’s entity mappings. Your QClasses represent meta-model query information, not entity registration.

Hibernate entity resolution is directly tied to how Java persistence providers and Spring JPA repositories interpret the entity metadata from annotations and package scanning. Here’s the catch:

Hibernate 6.x and Spring Boot 3.x now exclusively rely on the Jakarta Persistence API (Jakarta EE Persistence API). Often, the issue here is mistakenly mixing javax (old JPA) with jakarta (newer JPA) annotations. If any dependency still references javax.persistence annotations or classes, it won’t recognize your entity class at runtime.

The Solution—How to Resolve This Issue Once and For All

Here’s what you need to do to solve this problem definitively:

1. Verify entity annotations: Ensure your entity annotation imports are from jakarta.persistence.*, not javax.persistence. For instance:

   import jakarta.persistence.Entity;
   import jakarta.persistence.GeneratedValue;
   import jakarta.persistence.Id;
   import jakarta.persistence.GenerationType;

2. Confirm your build.gradle matches Spring Boot 3.x (Hibernate 6.x):
   • The com.querydsl:querydsl-apt:5.0.0:jakarta and com.querydsl:querydsl-jpa:5.0.0:jakarta versions should match.
   • Remove all javax.persistence imports in your code and dependencies.
3. Check Spring Boot scanning behavior explicitly. Perhaps your entity isn’t being scanned properly. Use explicit package scanning by setting:

   @SpringBootApplication
   @EntityScan(basePackages = "com.example.project.domain")
   @EnableJpaRepositories(basePackages = "com.example.project.repository")
   public class Application { ... }
       

4. Clean and rebuild your project thoroughly to remove old generated files and cached metadata.

Implementing these steps solves the Hibernate “UnknownEntityException” problem completely, ensuring proper recognition between QueryDSL and Hibernate in Spring Boot 3.2.3.

If you’ve struggled with Hibernate before, you’ll find this solution refreshingly straightforward. It highlights the importance of understanding the subtle API changes introduced with Jakarta EE, especially when migrating or upgrading your project.

Taking the time to correctly configure dependencies and ensure consistency across annotations and imports will save countless debugging hours down the road.

Have you encountered this QueryDSL-Hibernate recognition challenge in your own projects? Share your experiences and how you resolved them below or ask a question on Stack Overflow to engage with other developers’ solutions.