Hibernate JPQL原生查询报错：‘列不存在’与‘找不到命名参数’

一、"column does not exist" 错误排查与解决 #

• 混淆实体属性名与数据库列名
  原生查询直接操作数据库表，必须用数据库实际列名，不能用实体类的属性名。比如实体类里是userName，数据库列是user_name，写原生SQL时用userName就会报错。
  解决：核对数据库表结构，确保SQL里的列名和数据库完全一致，注意大小写（比如PostgreSQL对大小写敏感，驼峰列名需要加双引号，如"userName"）。

• 表名/列名拼写错误
  比如把create_time写成creat_time，或者表名少写后缀，这类低级错误很容易触发报错。
  解决：先在数据库客户端执行一遍SQL，确认能正常运行后再复制到代码里。

• 多表关联时未指定表别名
  多表查询时，相同列名如果不指定所属表/别名，会导致数据库无法识别；或者别名对应关系写错。
  错误示例SQL：

  SELECT id, name FROM user u JOIN role r ON u.role_id = r.id WHERE name = 'admin'
  

  这里name列在两个表中都存在，数据库不知道取哪个，直接报错。
  解决：给列加上表别名明确归属：

  SELECT u.id, u.name FROM user u JOIN role r ON u.role_id = r.id WHERE u.name = 'admin'
  

二、"Could not locate named parameter" 错误排查与解决 #

• 未启用原生查询的命名参数支持
  Hibernate默认对原生查询的命名参数支持不是自动开启的，直接用:param可能会识别失败。
  解决：使用createNativeQuery创建查询后，调用setParameter绑定参数；部分版本需要额外设置Hint开启支持：

  String sql = "SELECT * FROM user WHERE age > :userAge";
  Query query = entityManager.createNativeQuery(sql, User.class);
  query.setHint("hibernate.query.namedParametersEnabled", true);
  query.setParameter("userAge", 18);
  

• 参数名拼写不一致
  SQL里写的是:userName，代码里setParameter用的是user_name或者大小写不匹配，都会导致找不到参数。
  解决：严格核对SQL中的参数名和setParameter的第一个参数，确保完全一致，包括大小写。

• 混用位置参数与命名参数
  原生查询里同时用?1（位置参数）和:param（命名参数），会导致Hibernate解析逻辑混乱。
  错误示例：

  SELECT * FROM user WHERE name = ?1 AND age > :userAge
  

  解决：统一使用一种参数风格，要么全用位置参数，要么全用命名参数。

• 参数被字符串包裹
  如果把:param写在单引号里面，Hibernate会把它当成普通字符串，不会识别为参数。
  错误示例：

  SELECT * FROM user WHERE name = ':userName'
  

  解决：去掉参数外面的单引号，Hibernate会自动处理参数的字符串拼接：

  SELECT * FROM user WHERE name = :userName
  

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