适用版本： 7.x-8.x
1. 错误异常的基本描述 #
failed to parse [query] query. Invalid grid name [name] 表示查询里确实提供了 grid，但该值不是 Elasticsearch 当前支持的网格类型。
从源码看，这里只接受 geotile 和 geohash。只要传入其他字符串，就会立即抛出解析异常。
2. 常见原因 #
- 拼写错误，例如写成
geo_tile、hash、tile。 - 使用了业务自定义枚举值，没有在发请求前转换成 ES 支持值。
- 不同版本或不同组件之间字段语义混淆。
3. 如何排查和解决这个异常 #
- 查看报错中的
[name]，确认实际传入值。 - 检查调用链是否把内部枚举直接透传给 Elasticsearch。
- 用最小请求体验证目标版本到底支持哪些值。
常见有效值 #
geotilegeohash
4. 解决建议 #
- 把无效值改成 Elasticsearch 支持的网格名称。
- 在应用层增加枚举白名单，不允许任意字符串透传。
- 对多语言 SDK 或配置中心统一做字段映射，避免拼写漂移。
5. 小结 #
这条错误说明 grid 字段“有值但值不合法”。把它改成 geotile 或 geohash 即可。
相关错误 #
- failed-to-parse-query-grid-name-not-provided-how-to-solve-this-elasticsearch-exception
- failed-to-parse-query-grid-id-not-provided-how-to-solve-this-elasticsearch-exception
附：日志上下文 #
} else if (GEOTILE.getName().equals(name)) {
return GEOTILE;
} else if (GEOHASH.getName().equals(name)) {
return GEOHASH;
} else {
throw new ElasticsearchParseException("failed to parse [{}] query. Invalid grid name [" + name + "]", NAME);
}
} }
```---
title: "解析查询失败，无效的网格名称 - 如何解决此 Elasticsearch 异常"
date: "2026-03-03T08:00:00+08:00"
blogAuthor: "INFINI Labs"
category: "elasticsearch_errors"
blogAuthorDesc: "追求极致，无限可能。"
tags: ["查询解析", "geo grid", "网格名称", "Elasticsearch异常"]
blogImage: "/img/blog/request-logging/bg.png"
description: "当网格名称既不是 geotile 也不是 geohash 等受支持值时，Elasticsearch 会抛出 failed to parse query. Invalid grid name。本文说明其触发原因和修复方法。"
lang: "cn"
layout: "infini/knowledge-detail"
---
> **适用版本：** 8.3-8.9
## 1. 错误说明
报错 `failed to parse [<query>] query. Invalid grid name [<name>]` 表示解析器收到了网格名称，但该值不在 Elasticsearch 支持的网格类型集合内。
附录源码展示得很清楚：解析器只接受若干固定名称，匹配不到就直接报 `Invalid grid name`。
## 2. 常见原因
- 拼写错误，例如把 `geotile` 写成 `geo_tile`。
- 把业务层自己的名称直接透传给 Elasticsearch。
- 版本兼容性理解错误，以为某个网格类型受支持，实际上当前版本并不支持。
## 3. 排查方法
1. 提取异常中的网格名称原值。
2. 核对当前版本支持哪些网格类型。
3. 检查程序是否做了大小写转换、下划线替换或别名映射。
## 4. 修复方法
把网格名称改为受支持值。例如源码片段显示至少支持 `geotile` 和 `geohash`，因此应使用类似下面的写法：
```json
{
"query": {
"geo_grid": {
"field": "location",
"grid": "geotile",
"grid_id": "7/64/42"
}
}
}
5. 预防建议 #
- 为网格名称做枚举白名单。
- 在配置层维护别名到真实值的统一映射。
- 升级版本后核对受支持查询参数。
相关错误 #
附：日志上下文 #
} else if (GEOTILE.getName().equals(name)) {
return GEOTILE;
} else if (GEOHASH.getName().equals(name)) {
return GEOHASH;
} else {
throw new ElasticsearchParseException("failed to parse [{}] query. Invalid grid name [" + name + "]"; NAME);
}
} }
