适用版本： 7.x-8.x
1. 错误异常的基本描述 #
failed to parse [query] query. grid id not provided 表示 Elasticsearch 已经知道要按哪种网格类型解析，但没有拿到具体的 grid_id，因此无法定位目标网格单元。
源码显示该异常发生在 grid != null 之后，因此这里缺的是网格值，不是网格类型。
2. 常见原因 #
- 请求只传了
grid，没有传grid_id。 grid_id被渲染为空字符串或null。- 字段被写错名字，例如写成
gridId、id等。
3. 如何排查和解决这个异常 #
- 检查最终请求中是否存在
grid_id。 - 确认字段名与版本要求一致，不要用自定义别名。
- 检查空值过滤逻辑，避免把空字符串传给 ES。
错误示例 #
{
"query": {
"geo_grid": {
"grid": "geotile",
"location": "31.2304,121.4737"
}
}
}
4. 解决建议 #
- 补充合法的
grid_id值。 - 在模板层把
grid_id设为必填字段。 - 若
grid_id由上游系统计算，先确认计算逻辑没有返回空值。
5. 小结 #
这条错误很直接，表示网格查询少了真正用于定位单元格的 grid_id。补齐该字段即可继续解析。
相关错误 #
- failed-to-parse-query-grid-name-not-provided-how-to-solve-this-elasticsearch-exception
- failed-to-parse-query-invalid-grid-name-name-how-to-solve-this-elasticsearch-exception
附：日志上下文 #
if (grid == null) {
throw new ElasticsearchParseException("failed to parse [{}] query. grid name not provided", NAME);
}
if (gridId == null) {
throw new ElasticsearchParseException("failed to parse [{}] query. grid id not provided", NAME);
}
GeoGridQueryBuilder builder = new GeoGridQueryBuilder(fieldName);
builder.setGridId(grid, gridId);
builder.queryName(queryName);
builder.boost(boost);
```---
title: "解析查询失败，未提供网格 ID - 如何解决此 Elasticsearch 异常"
date: "2026-02-23T08:00:00+08:00"
blogAuthor: "INFINI Labs"
category: "elasticsearch_errors"
blogAuthorDesc: "追求极致，无限可能。"
tags: ["Elasticsearch", "geo grid", "grid id", "异常处理"]
blogImage: "/img/blog/request-logging/bg.png"
description: "当 GeoGridQueryBuilder 在解析请求时没有拿到 grid id，就会抛出 failed to parse query. grid id not provided。本文说明其含义和修复方式。"
lang: "cn"
layout: "infini/knowledge-detail"
---
> **适用版本：** 8.3-8.9
## 1. 错误说明
报错 `failed to parse [<query>] query. grid id not provided` 表示 Elasticsearch 已经识别到这是一个基于地理网格的查询，但没有读到实际要匹配的网格 ID。
从附录代码可见，解析器会先检查 `grid`，再检查 `gridId`。如果 `gridId == null`，就直接抛出该异常。
## 2. 常见触发场景
- 只指定了网格类型，没有提供具体网格编号。
- 请求体字段名写错，导致实际 grid id 没被解析到。
- 业务层把网格 id 作为可选值，结果拼装出不完整 DSL。
## 3. 排查方法
1. 检查请求里是否同时存在网格名称和网格 ID。
2. 确认 grid id 字段没有被序列化为空字符串或 null。
3. 检查客户端字段映射，确认没有把 `grid_id`、`id`、`value` 等名称混用。
## 4. 修复方法
为查询补齐合法的 grid id，例如：
```json
{
"query": {
"geo_grid": {
"field": "location",
"grid": "geotile",
"grid_id": "7/64/42"
}
}
}
具体字段名需要以实际 API 支持格式为准，但原则是不允许缺少目标网格 ID。
5. 预防建议 #
- 把网格名称和网格 ID 设为同时必填。
- 对地理网格查询做请求前校验。
- 在日志中单独记录网格类型和 grid id，便于定位。
相关错误 #
附：日志上下文 #
if (grid == null) {
throw new ElasticsearchParseException("failed to parse [{}] query. grid name not provided"; NAME);
}
if (gridId == null) {
throw new ElasticsearchParseException("failed to parse [{}] query. grid id not provided"; NAME);
}
GeoGridQueryBuilder builder = new GeoGridQueryBuilder(fieldName);
builder.setGridId(grid; gridId);
builder.queryName(queryName);
builder.boost(boost);
