适用版本： 7.x-8.x
1. 错误异常的基本描述 #
failed to parse [query] query. bounding box not provided 表示 Elasticsearch 已经识别到这是一个边界框查询，但请求里没有真正提供边界框对象，因此无法构造 GeoBoundingBoxQueryBuilder。
源码中只有在 bbox == null 时才会抛出这条异常，所以根因非常明确：边界框参数缺失，而不是字段 mapping 或执行阶段问题。
2. 常见触发场景 #
geo_bounding_box里只写了字段名，没有写top_left/bottom_right。- 经过模板渲染后，边界框对象被清空。
- 字段名写在了外层，但内部缺少任何有效坐标定义。
3. 如何排查和解决这个异常 #
- 检查
geo_bounding_box请求体里是否真的存在边界框对象。 - 确认至少有一组完整的边界信息，例如
top_left与bottom_right。 - 如果请求由程序拼装，打印最终发给 Elasticsearch 的 JSON，而不是只看变量模板。
错误示例 #
{
"query": {
"geo_bounding_box": {
"location": {}
}
}
}
正确示例 #
{
"query": {
"geo_bounding_box": {
"location": {
"top_left": { "lat": 40.73, "lon": -74.1 },
"bottom_right": { "lat": 40.01, "lon": -71.12 }
}
}
}
}
4. 解决建议 #
- 为
geo_bounding_box明确提供合法的边界框坐标。 - 如果边界框是可选参数，就在业务侧为空时不要生成该查询。
- 为请求构造逻辑增加非空校验，避免把空对象直接传入 ES。
5. 小结 #
这条错误不是“边界框格式不对”，而是“边界框根本没提供”。补齐 bbox 对象即可。
相关错误 #
- failed-to-parse-query-how-to-solve-this-elasticsearch-exception
- failed-to-parse-query-unexpected-field-how-to-solve-this-elasticsearch-exception
附：日志上下文 #
}
}
} if (bbox == null) {
throw new ElasticsearchParseException("failed to parse [{}] query. bounding box not provided", NAME);
} GeoBoundingBoxQueryBuilder builder = new GeoBoundingBoxQueryBuilder(fieldName);
builder.setCorners(bbox.topLeft(), bbox.bottomRight());
builder.queryName(queryName);
```---
title: "解析查询失败，未提供边界框 - 如何解决此 Elasticsearch 异常"
date: "2026-02-06T08:00:00+08:00"
blogAuthor: "INFINI Labs"
category: "elasticsearch_errors"
blogAuthorDesc: "追求极致，无限可能。"
tags: ["Elasticsearch", "geo_bounding_box", "地理查询", "异常处理"]
blogImage: "/img/blog/request-logging/bg.png"
description: "当 geo_bounding_box 查询缺少 bounding box 主体时，Elasticsearch 会抛出 failed to parse query. bounding box not provided。本文说明其触发原因与修复示例。"
lang: "cn"
layout: "infini/knowledge-detail"
---
> **适用版本：** 6.8-8.9
## 1. 错误说明
报错 `failed to parse [<query>] query. bounding box not provided` 表示 Elasticsearch 已经进入地理边界框查询解析流程，但直到结束都没有读到有效的 bounding box 对象。
从附录源码可见，只有当 `bbox == null` 时才会抛出这个异常，因此它通常意味着边界框整体缺失，而不是单个坐标值格式错误。
## 2. 常见触发场景
- 只写了字段名，没有写 `top_left` / `bottom_right`。
- 查询模板中边界框对象为空。
- 客户端把边界框参数过滤掉了，最终只剩一个空壳查询。
错误示例：
```json
{
"query": {
"geo_bounding_box": {
"location": {}
}
}
}
3. 排查方法 #
- 检查请求中是否真的存在边界框对象。
- 确认边界框是以
top_left/bottom_right、WKT 或其他受支持格式提供。 - 检查模板渲染或 SDK 转换过程中是否把空值字段删除掉。
4. 修复方法 #
必须提供完整的边界框定义，例如：
{
"query": {
"geo_bounding_box": {
"location": {
"top_left": {
"lat": 40.73,
"lon": -74.1
},
"bottom_right": {
"lat": 40.01,
"lon": -71.12
}
}
}
}
}
5. 预防建议 #
- 在发送请求前校验边界框对象非空。
- 将地理查询参数建模为必填对象，而不是任意 map。
- 对空搜索条件分支做单元测试，防止生成半成品 DSL。
相关错误 #
附：日志上下文 #
}
}
} if (bbox == null) {
throw new ElasticsearchParseException("failed to parse [{}] query. bounding box not provided"; NAME);
} GeoBoundingBoxQueryBuilder builder = new GeoBoundingBoxQueryBuilder(fieldName);
builder.setCorners(bbox.topLeft(); bbox.bottomRight());
builder.queryName(queryName);
