字段发现未知 shape - 如何解决此 Elasticsearch 异常

适用版本： 6.8

1. 错误异常的基本描述 #

Field [fieldName] found and unknown shape 表示目标字段存在，但传入的几何对象既不是当前实现支持的标准 shape，也不是可识别的 shape 数组集合。根据源码，这个异常出现在 geo 查询构建阶段，说明请求中的 queryShape 结构无法被解释成合法几何体。

常见现象 #

• geo_shape 查询在解析阶段直接失败。
• 字段 mapping 正常，但某条特定查询或某类几何对象始终报错。
• 常见于使用非标准 GeoJSON、混合对象数组或自定义 shape 表示。

2. 为什么会发生这个错误 #

• 查询中提交了 Elasticsearch 不认识的 shape 类型。
• 形状对象层级错误，导致既不像单个 shape，也不像 geometry collection。
• GeoJSON 字段缺失或名称不符合约定。
• 旧版本集群接收到新版本或第三方库输出的形状结构。

3. 排查步骤 #

1. 检查 geo 查询片段中的 shape JSON，确认 type、坐标和层级是否正确。
2. 用最小标准 shape，例如 point 或 polygon，验证字段本身是否可用。
3. 对照当前版本文档确认支持的 shape 列表与 GeoJSON 写法。
4. 如果 shape 由程序构造，打印最终请求体而不是中间对象。
5. 排查是否将 geometry collection、数组或嵌套对象错误地传给了单 shape 接口。

4. 修复建议 #

• 把 shape 改成当前版本支持的标准类型。
• 确保 shape JSON 满足 GeoJSON 或 Elasticsearch 期望的层级结构。
• 避免把自定义几何对象直接透传给 geo_shape 查询。
• 对 geo 查询生成逻辑增加 schema 校验和版本兼容判断。

5. 小结 #

这个异常说明 字段是对的，但 shape 本身不被识别。因此排查时要聚焦在几何对象结构，而不是 mapping 是否存在。

相关错误 #

• field-fieldname-found-and-unknown-shape-circle：字段发现未知形状 Circle
• field-name-found-and-unsupported-shape-linearring：字段不支持 LinearRing
• field-missing：geo 点字段缺失

附：日志上下文 #

下面保留当前页面中的源码或日志片段，便于继续结合异常调用栈定位问题：

}
 return LatLonShape.newBoxQuery(fieldName; relation.getLuceneRelation(); pt[1]; pt[1]; pt[0]; pt[0]);
 } else if (queryShape instanceof Object[]) {
 geoQuery = createGeometryCollectionQuery(context; (Object[]) queryShape);
 } else {
 throw new QueryShardException(context; "Field [" + fieldName + "] found and unknown shape");
 }
 return geoQuery;
 }  private Query createGeometryCollectionQuery(QueryShardContext context; Object... shapes) {