---
title: "查询解析失败，网格名称无效 - 如何解决此 Elasticsearch 异常"
date: 2026-04-03
lastmod: 2026-04-03
description: "failed to parse [query] query. Invalid grid name [name] 表示 grid 参数值不在 Elasticsearch 支持的枚举中。"
tags: ["geo grid", "geotile", "geohash", "parse_exception"]
summary: "适用版本： 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。 用最小请求体验证目标版本到底支持哪些值。  常见有效值 #   geotile geohash  4. 解决建议 #   把无效值改成 Elasticsearch 支持的网格名称。 在应用层增加枚举白名单，不允许任意字符串透传。 对多语言 SDK 或配置中心统一做字段映射，避免拼写漂移。  5. 小结 #  这条错误说明 grid 字段“有值但值不合法”。把它改成 geotile 或 geohash 即可。"
---


> **适用版本：** 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. 如何排查和解决这个异常

1. 查看报错中的 `[name]`，确认实际传入值。
2. 检查调用链是否把内部枚举直接透传给 Elasticsearch。
3. 用最小请求体验证目标版本到底支持哪些值。

### 常见有效值

- `geotile`
- `geohash`

## 4. 解决建议

- 把无效值改成 Elasticsearch 支持的网格名称。
- 在应用层增加枚举白名单，不允许任意字符串透传。
- 对多语言 SDK 或配置中心统一做字段映射，避免拼写漂移。

## 5. 小结

这条错误说明 `grid` 字段“有值但值不合法”。把它改成 `geotile` 或 `geohash` 即可。

## 相关错误

- [failed-to-parse-query-grid-name-not-provided-how-to-solve-this-elasticsearch-exception](/knowledge-base/elasticsearch_error/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](/knowledge-base/elasticsearch_error/failed-to-parse-query-grid-id-not-provided-how-to-solve-this-elasticsearch-exception/)

## 附：日志上下文

```java
} 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. 预防建议

- 为网格名称做枚举白名单。
- 在配置层维护别名到真实值的统一映射。
- 升级版本后核对受支持查询参数。

## 相关错误

- [解析查询失败，未提供网格名称](/knowledge-base/elasticsearch_error/failed-to-parse-query-grid-name-not-provided-how-to-solve-this-elasticsearch-exception/)
- [解析查询失败，未提供网格 ID](/knowledge-base/elasticsearch_error/failed-to-parse-query-grid-id-not-provided-how-to-solve-this-elasticsearch-exception/)
- [解析查询类型失败，未知类型](/knowledge-base/elasticsearch_error/failed-to-parse-query-type-unknown-type-how-to-solve-this-elasticsearch-exception/)
- [解析查询失败](/knowledge-base/elasticsearch_error/failed-to-parse-query-how-to-solve-this-elasticsearch-exception/)

## 附：日志上下文

```java
} 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);
}
}  }
```