JPA抛出IllegalArgumentException：Not an entity: class问题求助

这问题我之前排查过类似的，JPQL能正常跑但Criteria API报错，大概率是Criteria API的使用姿势不对，或者类加载/类型匹配的问题，咱们一步步来解决：

1. 先检查CriteriaQuery的初始化方式（最常见的坑） #

很多人会忽略CriteriaQuery必须通过EntityManager的CriteriaBuilder来创建，并且要指定实体类型。你的代码里有没有正确初始化query？正确的写法应该是这样：

// 先获取CriteriaBuilder
CriteriaBuilder cb = entityManager.getCriteriaBuilder();
// 创建绑定到pType的CriteriaQuery
CriteriaQuery<T> query = cb.createQuery(pType);
// 从实体类创建Root对象
Root<T> root = query.from(pType);
// 选择查询结果
query.select(root);
// 生成TypedQuery并执行
TypedQuery<T> queryAll = entityManager.createQuery(query);
return queryAll.getResultList();

如果你的query是直接new出来的（比如new CriteriaQueryImpl<>()），没有关联到正确的实体类型，JPA就会识别不出这是它管理的实体类，直接抛出异常。

2. 验证pType的类加载器是否和EntityManager一致 #

在多模块、容器化或者使用自定义类加载器的场景下，同一个类可能被不同的类加载器加载，导致JPA认为pType不是它管理的实体（虽然类名相同，但Class对象不相等）。你可以加一段调试代码确认：

// 打印EntityManager管理的所有实体类
Set<Class<?>> managedEntities = entityManager.getMetamodel().getEntities().stream()
    .map(Type::getJavaType)
    .collect(Collectors.toSet());
System.out.println("JPA管理的实体类：" + managedEntities);
System.out.println("pType是否被管理？" + managedEntities.contains(pType));

如果输出是false，那就是类加载器的问题，需要确保获取pType的类加载器和EntityManager使用的一致（比如用JPA容器的类加载器加载实体类，避免自定义类加载器重复加载）。

3. 再检查persistence.xml的配置细节 #

虽然你说已经声明了实体，但可能存在细节错误：

• 确认<exclude-unlisted-classes>是否设置为true，如果是，必须把pType对应的实体类手动添加到<class>标签里，不能漏；
• 检查实体类的全类名是否拼写正确，比如包名有没有写错；
• 有些JPA实现（比如Hibernate）支持自动扫描@Entity注解的类，但如果persistence.xml里配置了<exclude-unlisted-classes>true</exclude-unlisted-classes>，自动扫描就会失效，必须手动列出所有实体。

4. 确认@Entity注解的导入是否正确 #

确保实体类上的@Entity注解是JPA标准的，而不是其他框架的同名注解：

// JPA 2.x及之前的正确导入
import javax.persistence.Entity;
// Jakarta EE 9+（JPA 3.x）的正确导入
import jakarta.persistence.Entity;

如果不小心导入了其他包的@Entity（比如Spring的一些扩展注解），JPA是不会识别这个类为实体的。

内容的提问来源于stack exchange，提问作者Hejk