# Easysearch | 分布式搜索引擎 | INFINI Labs > AI-friendly index of site content. ## Core Content - [为什么企业需要 Easysearch ？](https://easysearch.cn/knowledge-base/insight/why-enterprises-need-easysearch/): 在信创替代全面提速的 2026 年，企业级搜索引擎的选型正从"技术偏好"转向"战略决策"。当 Elasticsearch 的许可证频繁变更带来合规风险，当核心数据安全成为不可触碰的红线，当国产化适配进入倒计时——Easysearch 作为面向未来的国产企业级搜索引擎，正在成为关键行业的不二之选。 一、合规即底线：解决信创与安全的两难 # 信创不是简单 … - [为何说 Easysearch 是构建安全可控数据基座的优选？](https://easysearch.cn/knowledge-base/insight/why-easysearch-is-the-preferred-choice-for-a-secure-and-controllable-data-foundation/): 当一家金融机构的核心日志分析平台在深夜遭遇异常高频查询攻击时，其新部署的国产搜索引擎不仅实时识别并阻断了该行为，还自动完成了全量字段级脱敏，保障了数亿条客户敏感信息无一泄露——这不再是技术设想，而是正在发生的现实。 在数字主权日益重要的今天，“数据基座”已从技术概念演变为企业核心战略资产。一个真正安全可控的数据基座，必须同时满足技术先进、合规可靠、自主可控、成本高效四大核心要素。 … - [信创是什么？为什么搜索引擎也要“国产自主可控”？](https://easysearch.cn/knowledge-base/insight/what-is-xinchuang-and-why-search-engines-must-be-domestically-controllable/): 2023 年，一家大型金融机构在进行信创改造时发现，其核心的日志分析系统底层完全依赖于国外开源的 Elasticsearch（ES）。这个发现让项目组惊出一身冷汗——他们意识到，替换办公软件只是开始，真正核心的业务系统底层，还藏着巨大的“断供”风险。 01 信创：一场深度的信息技术体系重构 # 信创，即 “信息技术应用创新” 。它远非简单的“软件国产化”，而是一场在国家层面推动的、旨在实现信息 … - [如果继续使用 Elasticsearch，最坏会发生什么](https://easysearch.cn/knowledge-base/insight/what-is-the-worst-case-if-you-keep-using-elasticsearch/): —— 面向 CTO / CIO 的风险情景分析报告（2026） # 一、为什么需要讨论“最坏情况” # 在多数企业内部，Elasticsearch 仍被视为一种“已经稳定运行多年的成熟技术”。正因为这种长期使用形成的技术惯性，关于其风险的讨论往往被延后，甚至被刻意弱化。 然而，站在 2026 年这一时间节点，Elasticsearch 所面临的问题，已经不再是性能、功能或生态层面的技术讨论， … - [信创背景下的必然选择：为什么说企业级搜索引擎必须自主可控？](https://easysearch.cn/knowledge-base/insight/under-xinchuang-why-enterprise-search-engines-must-be-autonomous-and-controllable/): 一、信创深水区：搜索引擎成为关键战场 # 2026 年，信创产业迎来关键转折。国资委 79 号文明确：2027 年前央企国企核心系统必须实现 100%信创替代。在这场从"可用"到"好用"的升级中，企业级搜索引擎——这个支撑电商检索、金融日志分析、政务文档管理的核心基础设施，正浮出水面。 长期以来，该领域被 Elasticsearch 等国外产品主导。当信创 … - [我为什么最终放弃了 Elasticsearch？一个架构师的国产化迁移复盘](https://easysearch.cn/knowledge-base/insight/why-i-abandoned-elasticsearch-domestic-migration-retrospective/): 作为一名拥有多年分布式系统架构经验的技术负责人，我曾是 Elasticsearch 的忠实用户。然而，在 2024 年我们团队做出了一个重大决定：将核心搜索业务从 Elasticsearch 迁移至国产的 Easysearch。这次迁移不仅是一次技术栈的更换，更是我们对技术自主可控战略的深刻实践。 一、放弃 Elasticsearch 的核心原因 # 1.1 开源协议变更带来的风险 # … - [告别“卡脖子”：传统 ES 在信创环境中面临的挑战与应对](https://easysearch.cn/knowledge-base/insight/saying-goodbye-to-lock-in-traditional-es-challenges-and-strategies-in-xinchuang-environments/): 2025 年初，一家省级政务云平台在信创验收评估中被指出“核心日志分析组件存在供应链风险”，其基于 Elasticsearch 的技术栈因不完全符合信创要求而被要求限期整改。这并非孤例，随着信创进入“真替真用”的深水区，类似场景正在金融、能源、电信等关键行业反复上演。 信创（信息技术应用创新）已从局部试点演变为国家层面推动的关键基础设施重建运动。根据行业调研， … - [SSPL 协议真的只是“云托管不行”？企业开源选型的合规陷阱与破局之道](https://easysearch.cn/knowledge-base/insight/is-sspl-just-no-cloud-hosting-compliance-traps-and-breakthroughs-in-enterprise-open-source-selection/): 引言：协议选择决定企业命运，开源选型不能只看“表面自由” # 在数字化转型中，开源软件已成为企业构建 IT 基础设施的核心选择，但 “免费开源” 背后的协议条款，往往暗藏影响业务发展的关键限制。 Server Side Public License（SSPL）作为近年来争议较大的开源协议，常被简单理解为“禁止云托管”，但这一认知背后，隐藏着可能让企业陷入合规风险的深层陷阱。 … - [隐秘的“电话线”：从数据遥测审视国外基础软件的数据主权与合规风险](https://easysearch.cn/knowledge-base/insight/hidden-telemetry-lines-data-sovereignty-and-compliance-risks-in-foreign-infrastructure-software/): 深夜，某金融机构数据中心的管理员收到一条安全告警：一台核心业务服务器正在向一个位于海外的陌生 IP 地址持续发送加密数据包。追踪发现，流量源头并非恶意软件，而是他们常年使用的、一款国际知名的数据库管理软件内置的“用户体验改进计划”功能。 在全球化技术栈的背后，一条条隐形的 “数据电话线” 正悄然运行。它们以遥测之名，将软件运行状态、性能指标乃至操作元数据，源源不断地传回位于他国的服务器。随着数据 … - [can't get contents for setting jwksetconfigkeypkc value jwksetpathpkcuri - JWK 内容读取失败如何解决](https://easysearch.cn/knowledge-base/elasticsearch_error/can-t-get-contents-for-setting-jwksetconfigkeypkc-value-jwksetpathpkcuri-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.x 1. 错误异常的基本描述 # Can't get contents for setting [jwkSetConfigKeyPkc] value [jwkSetPathPkcUri] 表示 Elasticsearch 在读取 OpenID Connect（OIDC）或 JWT 认证配置中的 JSON Web Key（JWK）内容时失败。这个错误发生在读取动作本身，而不是后续 … - [claim 值类型不正确 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/setting-settingkey-expects-a-claim-with-string-or-a-string-array-value-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.x 1. 错误异常的基本描述 # Setting [...] expects a claim with String or a String Array value 表示 Elasticsearch 在从 Token claim 中读取某个安全配置值时，发现该 claim 的类型不是字符串，也不是字符串数组。 常见现象 # 认证流程在解析用户属性、角色映射或 realm … - [failed to get binary value - 获取二进制值失败](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-get-binary-value-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.x-8.9 1. 错误异常的基本描述 # Failed to get binary value 表示 Elasticsearch 已经定位到某个二进制（binary）字段值，但在将其写入内部输出流并转换成 BytesRef 时发生了 IOException。这不是"字段不存在"的直接报错，而是字段值读取或序列化阶段失败，常见于二进制字段返回、字段加载、脚本处 … - [failed to get claims from the Userinfo Endpoint - 从 UserInfo Endpoint 获取 Claims 失败](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-get-claims-from-the-userinfo-endpoint-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.x-8.9 1. 错误异常的基本描述 # Failed to get claims from the Userinfo Endpoint. 表示 Elasticsearch 的 OIDC（OpenID Connect）Realm 已经开始向身份提供方（Identity Provider，IdP）的 UserInfo Endpoint 取回用户 claims，但 HTTP 请求最 … - [failed to get claims from the Userinfo Endpoint, request was cancelled - 从 UserInfo Endpoint 获取 Claims 失败，请求已取消](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-get-claims-from-the-userinfo-endpoint-request-was-cancelled-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.x-8.9 1. 错误异常的基本描述 # Failed to get claims from the Userinfo Endpoint. Request was cancelled 表示 Elasticsearch 的 OIDC（OpenID Connect）Realm 已经向身份提供方（Identity Provider，IdP）的 UserInfo Endpoint 发起 … - [failed to get id [id] - 获取文档 ID 失败](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-get-id-id-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.x-8.9 1. 错误异常的基本描述 # Failed to get id [id] 表示 Elasticsearch 已经定位到了目标文档所在的 Lucene reader，但在把 stored fields loader 推进到该文档时发生了 IOException。这不是简单的"文档不存在"——如果只是找不到文档，通常会返回正常的 404 Not … - [failed to get id [id] with includes/excludes set - 获取文档 ID 失败，且设置了 includes/excludes](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-get-id-id-with-includes-excludes-set-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.x-8.9 1. 错误异常的基本描述 # Failed to get id [id] with includes/excludes set 表示 Elasticsearch 已经取到了文档的 _source，但在按照 includes/excludes 规则做字段过滤时失败。相比普通的 Failed to get id [id]，这个异常更明确地指向 _source 过滤阶段， … - [failed to get setting group for settingPrefix, setting [setting] because of a missing '.' - 获取设置分组失败，缺少点号](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-get-setting-group-for-settingprefix-setting-prefix-and-setting-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.x-8.9 1. 错误异常的基本描述 # Failed to get setting group for [settingPrefix] setting prefix and setting [setting] because of a missing '.' 表示 Elasticsearch 在按前缀提取一组配置项时， … - [failed to get type [type] and id [id] - 获取 type 和 ID 失败](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-get-type-type-and-id-id-how-to-solve-this-elasticsearch-exception/): 适用版本： 5.6-7.x（typed API 已废弃，8.x 已移除） 1. 错误异常的基本描述 # Failed to get type [type] and id [id] 出现在旧版带 type 的 Get API 路径中，表示 Elasticsearch 在通过 Lucene reader 读取该文档的 stored fields 时失败。它与 typeless 版本的 Failed … - [failed to get type [type] and id [id] with includes/excludes set - 获取 type 和 ID 失败，且设置了 includes/excludes](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-get-type-type-and-id-id-with-includes-excludes-set-how-to-solve-this-elasticsearch-exception/): 适用版本： 5.6-7.x（typed API 已废弃，8.x 已移除） 1. 错误异常的基本描述 # Failed to get type [type] and id [id] with includes/excludes set 表示旧版 typed get 请求已经拿到了文档 _source 并转成 map，但在按 includes/excludes 过滤后重新构建返回内容时失败。这个异 … - [failed to get user information from the UserInfo endpoint - 从 UserInfo Endpoint 获取用户信息失败](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-get-user-information-from-the-userinfo-endpoint-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.x-8.9 1. 错误异常的基本描述 # Failed to get user information from the UserInfo endpoint. 表示 Elasticsearch 在 OIDC 登录流程中已经开始访问 UserInfo Endpoint，但整个获取或处理过程抛出了异常。相比只针对 claims 的异常（Failed to get claims … - [failed to get user information from the UserInfo endpoint, Code=[code] - 从 UserInfo Endpoint 获取用户信息失败并返回错误码](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-get-user-information-from-the-userinfo-endpoint-code-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.x-8.9 1. 错误异常的基本描述 # Failed to get user information from the UserInfo endpoint. Code=[...]; Description=[...] 表示 Elasticsearch 确实收到了 UserInfo Endpoint 的 HTTP 响应，但响应不是成功状态（非 2xx），并且还能提取出明确的错误 … - [failed to parse add user request, unexpected field - 解析 add user 请求失败，出现未预期字段](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-add-user-request-unexpected-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.x-8.x 1. 错误异常的基本描述 # failed to parse add user request. unexpected field [{}] 表示 Elasticsearch 在解析创建用户（add user）请求体时，读到了当前接口不认识的字段名，因此直接拒绝该请求。从日志上下文可以看到，解析器在遍历请求字段时，如果当前字段不属于允许集合， … - [failed to parse aliases - 解析 aliases 失败](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-aliases-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.x 1. 错误异常的基本描述 # Failed to parse aliases 表示 Elasticsearch 在遍历 aliases 配置时发生了 IOException，导致别名定义无法完成解析。从日志上下文看，解析器会循环读取 aliases 对象中的每个别名，并调用 Alias.fromXContent(parser)。只要中间出现 I/O 或结构解析异常， … - [failed to parse bounding box, conflicting definition found - 解析 bounding box 时发现冲突定义](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-bounding-box-conflicting-definition-found-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.x-8.9 1. 错误异常的基本描述 # failed to parse bounding box. Conflicting definition found 表示 Elasticsearch 在解析地理边界框（bounding box）时，发现同一个 bounding_box 被用两种互斥方式同时定义了。从日志上下文看，解析器已经拿到了 envelope（WKT 格式），同时 … - [failed to parse bounding box, expected start object but found - 解析 bounding box 时期望对象但找到其他 token](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-bounding-box-expected-start-object-but-found-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.x-8.9 1. 错误异常的基本描述 # failed to parse bounding box. Expected start object but found [...] 表示 Elasticsearch 在解析地理边界框（bounding box）时，预期当前位置应该是一个 JSON 对象的开始（即 {），但实际遇到了别的 token（如字符串、数组、数字等）。从源码 … - [failed to parse bounding box, field name expected but found - 解析 bounding box 时期望字段名但找到其他 token](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-bounding-box-field-name-expected-but-found-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.x-8.9 1. 错误异常的基本描述 # failed to parse bounding box. field name expected but [...] found 表示 Elasticsearch 已经进入了 bounding_box 对象内部，但在应该读取字段名的位置遇到了不合法的 token。简单说，就是对象里的 JSON 结构坏了。 这不是地理计算错误，而是更早 … - [failed to parse bounding box, unexpected field - 解析 bounding box 时出现未预期字段](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-bounding-box-unexpected-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.x-8.9 1. 错误异常的基本描述 # failed to parse bounding box. unexpected field [...] 表示 Elasticsearch 已经识别出这是一个 bounding_box 对象，但对象里出现了未被该解析器支持的字段名。从源码片段看，解析器只接受少数几个固定字段（如 top_left、bottom_right 等），只要字段 … - [failed to parse change password request, unexpected field - 解析 change password 请求失败，出现未预期字段](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-change-password-request-unexpected-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.x-8.x 1. 错误异常的基本描述 # failed to parse change password request. unexpected field [{}] 表示 Elasticsearch 在解析修改密码请求时，发现了接口定义之外的字段，于是中止解析并返回错误。从日志上下文显示，这段代码先校验字段类型，再在未知字段分支抛出异常。也就是说，请求不仅要求字段名正确，还要 … - [failed to parse content to map - 无法解析内容为 Map](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-content-to-map-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.x-8.9 1. 错误异常的基本描述 # Failed to parse content to map 表示 Elasticsearch 在调用 XContentParser 将输入内容转换成 Map 时失败了。从日志上下文可以看到，convertToMap 内部只是创建解析器并调用 parser.map() 或 parser.mapOrdered()。 … - [failed to parse content to type - 无法解析内容为目标类型](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-content-to-type-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.x-8.9 1. 错误异常的基本描述 # Failed to parse content to type 表示 Elasticsearch 已经尝试为某段输入内容创建 XContentParser，并把它交给某个提取器（extractor）去生成目标类型，但在这个过程中失败了。它比 Failed to parse content to map 更泛化，因为目标可能不是 Map， … - [failed to parse index option - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-index-option-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.x-8.x 1. 错误异常的基本描述 # failed to parse index option [value] 表示 Elasticsearch 在解析字段映射（mapping）中的 index_options 配置时，发现传入的值不在当前版本支持的枚举范围内，从而拒绝该映射定义。 该异常属于 ElasticsearchParseException，通常在以下场景中触发： … - [failed to parse license - no content provided - 解析 License 失败，未提供内容](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-license-no-content-provided-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.x 1. 错误异常的基本描述 # failed to parse license - no content provided 表示 Elasticsearch 在解析 License 内容时，拿到的字节数组为空，或者根本没有收到任何正文。根据日志上下文，License.fromSource(BytesReference bytes, XContentType … - [failed to parse licenses expected an array of licenses - 解析 licenses 失败，预期为 license 数组](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-licenses-expected-an-array-of-licenses-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.x 1. 错误异常的基本描述 # failed to parse licenses expected an array of licenses 表示 Elasticsearch 在读取 licenses 字段时，期待得到一个数组，但实际拿到的不是数组结构。从日志上下文表明，解析器在处理 licenses 字段时只接受数组 token。若检测到的 token 不是数组开 … - [failed to parse, document is empty - 文档为空无法解析](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-document-is-empty-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.x-8.x 1. 错误异常的基本描述 # failed to parse, document is empty 表示 Elasticsearch 在解析待索引文档时，发现请求里确实传了 source，但它的长度为 0，也就是空文档。从日志上下文可以看到，源码在真正创建 XContentParser 之前就先检查： source.source() != null … - [failed to parse, expected 2 or 3 coordinates - geo_point 坐标数量错误](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-expected-2-or-3-coordinates-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.x-8.9 1. 错误异常的基本描述 # failed to parse, expected 2 or 3 coordinates 是 geo_point 解析阶段的格式校验异常，说明 Elasticsearch 期望拿到一个合法的单点坐标输入（2 个坐标：纬度和经度；或 3 个坐标：加高度），但当前内容不满足坐标数量要求。 从日志片段看，底层逻辑会把字符串拆成多个坐标段，然后 … - [failed to parse, expected 2 or 3 coordinates but found - geo_point 坐标数量错误](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-expected-2-or-3-coordinates-but-found-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.x-8.9 1. 错误异常的基本描述 # failed to parse [...]; expected 2 or 3 coordinates but found: [...] 表示 Elasticsearch 在把一个坐标字符串解析成 GeoPoint 时，发现拆分后的坐标数量不对。它要求输入只能包含： 2 个坐标值：纬度和经度（如 "lat, … - [HMAC 密钥解析失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/hmac-key-parse-failed-for-setting-jwksetconfigkey-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.x 1. 错误异常的基本描述 # HMAC Key parse failed for setting [...] 表示 Elasticsearch 已经成功拿到了配置中的密钥内容，但在把它转换成 HMAC JWK 时失败。 常见现象 # 安全相关配置加载时直接报错，节点可能拒绝启用对应 realm 或认证能力。 日志会明确指出出错的设置键， … - [JWKSet 解析失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/jwkset-parse-failed-for-setting-jwksetconfigkey-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.x 1. 错误异常的基本描述 # JWKSet parse failed for setting [...] 表示 Elasticsearch 已经拿到配置内容，但 JWKSet.parse(...) 失败，说明内容格式不是合法的 JSON Web Key Set。 常见现象 # 安全配置加载或认证流程初始化失败。 日志中会指向具体的设置键，但不会说明每个字段哪里错，需要查 … - [OpenID Connect 客户端密钥缺失 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/the-configuration-setting-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.x-8.x 1. 错误异常的基本描述 # 当前日志上下文中的 The configuration setting [...] is required 具体对应的是 OIDC realm 的 RP_CLIENT_SECRET。也就是说，Elasticsearch 在初始化 OpenID Connect realm 时发现客户端密钥为空。 常见现象 # OIDC realm 无 … - [Realm claim 设置缺失 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/setting-realmsettings-getfullsettingkey-realmconfig-setting-getclaim-is-required-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.17-8.9 1. 错误异常的基本描述 # Setting [RealmSettings.getFullSettingKey(..., setting.getClaim())] is required 表示当前安全 realm 的某个 claim 配置项被标记为必填，但在实际配置中未找到对应的值。Elasticsearch 在加载 realm 配置时会校验必填项，一旦发现缺失便 … - [realm 必填配置缺失 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/the-configuration-setting-realmsettings-getfullsettingkey-config-setting-is-required-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.17-8.9 1. 错误异常的基本描述 # The configuration setting [<setting_key>] is required 是 Elasticsearch 安全模块在初始化认证 realm 时抛出的 SettingsException。该异常明确表示：某个 realm 的必填配置项虽然被读取到了，但其值为空字符串，因此被视为未配置， … - [Token 响应中缺少 ID Token 或 JWT 解析失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/token-response-did-not-contain-an-id-token-or-parsing-of-the-jwt-failed-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.x-8.x 1. 错误异常的基本描述 # Token Response did not contain an ID Token or parsing of the JWT failed. 表示 Elasticsearch 在完成 OIDC（OpenID Connect）授权码交换后，无法从 Token Endpoint 的响应中拿到一个可解析的 ID Token JWT。该异常 … - [Token 响应中缺少 ID Token 或返回内容无法解析 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/token-response-did-not-contain-an-id-token-or-parsing-of-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.x-8.x 1. 错误异常的基本描述 # Token Response did not contain an ID Token or parsing of the response failed 表示 Elasticsearch 的 OIDC 安全域（Realm）在调用身份提供商（IdP）的 Token Endpoint 后，未能从响应中提取到合法的 id_token，或者响应 … - [UserInfo 响应与 ID Token 中的 subject 不一致 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/userinfo-response-is-not-valid-as-it-is-for-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.x-8.x 1. 错误说明 # Userinfo Response is not valid as it is for subject [...] while the ID Token was for subject [...] 表示 Elasticsearch 在执行 OpenID Connect（OIDC）身份认证时，发现从 UserInfo Endpoint 获取到的用户 … - [UserInfo 响应中缺少 sub 声明 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/userinfo-response-did-not-contain-a-sub-claim-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.x-8.x 涉及组件： Elasticsearch Security / OIDC Realm 1. 错误说明 # Userinfo Response did not contain a sub Claim 是 Elasticsearch 在使用 OpenID Connect (OIDC) 身份认证时抛出的安全异常。 当 Elasticsearch 配置了对接 OIDC … - [为 GET 操作创建内存段失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-create-an-in-memory-segment-for-get-operation-id-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.14-8.11 说明： 该异常的含义以下方源码片段为准。 1. 错误异常的基本描述 # failed to create an in-memory segment for get [id] 是 Elasticsearch 分片引擎层抛出的 EngineException。当客户端通过 GET /{index}/_doc/{id} 发起实时读取请求时，Elasticsearch … - [为嵌套文档的 Percolator 创建索引失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-create-index-for-percolator-with-nested-document-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.17-8.9 1. 错误异常的基本描述 # Failed to create index for percolator with nested document 出现在 Elasticsearch 执行 percolator 查询的准备阶段。Percolator 是一种"反向搜索"机制：先把查询存储为文档，再用传入的文档去匹配哪些查询命中。 … - [为机器学习创建本机进程工厂失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-create-native-process-factories-for-machine-learning-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.17-8.9 1. 错误异常的基本描述 # Failed to create native process factories for Machine Learning 是 Elasticsearch 机器学习模块在初始化本机进程工厂时抛出的异常。该异常表明 ML 原生控制器（native controller）已成功获取， … - [为机器学习创建本机进程控制器失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-create-native-process-controller-for-machine-learning-how-to-solve-this-elasticsearch-exception/): 说明： 该异常的含义以下方源码片段为准。 1. 错误异常的基本描述 # Failed to create native process controller for Machine Learning 出现在机器学习组件初始化自动检测进程工厂时。源码表明，若 NativeControllerHolder.getNativeController(...) 返回 null，Elasticsearch … - [为解析别名创建临时索引失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-create-temporary-index-for-parsing-the-alias-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.10-8.11 1. 错误异常的基本描述 # Failed to create temporary index for parsing the alias 表示 Elasticsearch 在解析别名（alias）的过滤器（filter）时，需要先临时创建一个索引并合并 mapping，以便验证和解析过滤条件中的字段类型；如果这一过程失败，就会抛出该异常。 需要特别说明的是，这 … - [交换授权码获取 ID Token 失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-exchange-code-for-id-token-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.17-8.9 1. 错误说明 # Failed to exchange code for Id Token 表示 Elasticsearch 在 OIDC 单点登录流程的回调阶段，访问 IdP（身份提供商）的 Token Endpoint 失败，未能完成授权码（Authorization Code）到 ID Token 的交换。 … - [交换授权码获取 ID Token 失败，Code=，Description= - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-exchange-code-for-id-token-code-description-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.x-8.x 1. 错误异常的基本描述 # Failed to exchange code for Id Token. Code=[...]; Description=[...] 表示 Elasticsearch 已经调用了 OpenID Connect 提供方的 Token Endpoint，但提供方返回了标准 OAuth2 错误响应。 常见现象 # 浏览器完成回调后登录失 … - [使用 Token Endpoint 交换授权码获取 ID Token 失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-exchange-code-for-id-token-using-the-token-endpoint-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.x-8.x 1. 错误异常的基本描述 # Failed to exchange code for Id Token using the Token Endpoint. 表示 Elasticsearch 在 OIDC 认证流程中，已成功获取授权码（Authorization Code），但在向 IdP（身份提供商）的 Token Endpoint 发起 HTTP 请求以交换 ID … - [创建 RescoreSearchContext 失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-create-rescoresearchcontext-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.17-8.9 1. 错误异常的基本描述 # failed to create RescoreSearchContext 表示 Elasticsearch 在执行搜索请求时，尝试为 rescore 阶段构建搜索上下文（SearchContext）失败，抛出了 SearchException。该异常通常发生在搜索请求包含 rescore 配置，而 Elasticsearch 在为每 … - [创建 Rollup 索引失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-create-rollup-index-rollupindexname-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.17-8.9 1. 错误异常的基本描述 # Failed to create rollup index [rollupIndexName] 表示 Elasticsearch 在执行 Rollup 作业时，尝试为目标 Rollup 数据创建索引，但索引创建请求未收到成功确认，导致整个 Rollup 任务失败。 Rollup 是 Elasticsearch 中用于将数据从原始索引按 … - [创建 SearchContextHighlighter 失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-create-searchcontexthighlighter-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.17-8.9 1. 错误异常的基本描述 # failed to create SearchContextHighlighter 表示 Elasticsearch 在执行搜索请求的高亮（highlight）阶段时，无法成功构建高亮上下文，最终抛出 SearchException。 … - [创建 SuggestionSearchContext 失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-create-suggestionsearchcontext-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.17-8.17 说明： 该异常的含义以下方源码片段为准。 1. 错误异常的基本描述 # failed to create SuggestionSearchContext 表示 Elasticsearch 在执行搜索请求时，尝试构建 suggest 上下文（SuggestionSearchContext）的过程中抛出了 IOException，导致请求在 suggest 阶段就失 … - [创建安全索引失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-create-security-index-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.17-8.9 1. 错误说明 # Failed to create security index 表示 Elasticsearch 安全模块在初始化过程中，尝试创建内部安全索引（如 .security-7 或 .security）后，未能收到 acknowledged 确认响应，从而在回调中主动抛出 ElasticsearchException。 该异常并非普通用户索引创建失 … - [创建引擎失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-create-engine-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.17-8.9 1. 错误异常的基本描述 # failed to create engine 表示 Elasticsearch 在启动分片（shard）时，无法成功初始化 Lucene 引擎（IndexWriter、提交点、translog 等核心组件），进而抛出 EngineCreationFailureException。这类异常属于分片级硬故障，一旦发生， … - [创建排序元素失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-create-sort-elements-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.17-8.9 1. 错误异常的基本描述 # failed to create sort elements 出现在 Elasticsearch 搜索请求的排序上下文初始化阶段。当 SortBuilder.buildSort(...) 在将 sort DSL 转换为可执行的排序对象时抛出 IOException，整个搜索请求就会以 SearchException 失败。 这意味着排 … - [创建新的 Translog 文件失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-create-new-translog-file-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.17-8.9 1. 错误异常的基本描述 # failed to create new translog file 表示 Elasticsearch 在创建新的 translog writer 文件时抛出了 IOException，随后被包装成 TranslogException。该异常发生在写入链路的最底层——translog 持久化阶段，意味着索引操作无法安全地写入事务日志， … - [创建本地检查点跟踪器失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-create-local-checkpoint-tracker-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8 - 8.12 1. 错误说明 # failed to create local checkpoint tracker 表示 Elasticsearch 在分片引擎启动阶段，尝试构建本地 checkpoint 跟踪器（LocalCheckpointTracker）时失败。该跟踪器负责维护分片级别已完成的序列号（sequence number）状态，是写入和恢复流程中的核心数据 … - [创建查询失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-create-query-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.17-8.9 1. 错误说明 # failed to create query 是 Elasticsearch 在执行搜索请求时，QueryShardException 的一种表现形式。该异常发生在查询的 rewrite 阶段之后、Lucene Query 对象构建之前，意味着 Elasticsearch 无法将用户提交的查询 DSL 转换为可执行的底层查询对象。 需要注意的 … - [创建空 Store 失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-create-empty-store-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # failed to create empty store 出现在分片恢复（recovery）阶段。当 Elasticsearch 尝试为一个分片初始化空的底层存储目录时，如果 store.createEmpty() 调用失败，就会抛出 IndexShardRecoveryException。 这不是搜索请求错误，而是分片恢复或初始化底层 … - [创建聚合器失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-create-aggregators-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.17-8.9 1. 错误异常的基本描述 # Failed to create aggregators 出现在搜索请求初始化阶段。源码显示，异常发生在 source.aggregations().build(aggContext, null) 构建聚合器工厂时，一旦底层抛出 IOException，Elasticsearch … - [无法使用 Token Endpoint 交换授权码获取 ID Token - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-exchange-code-for-id-token-using-token-endpoint-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.x-8.x 1. 错误异常的基本描述 # Failed to exchange code for Id Token using Token Endpoint. Expected client authentication method to be one of ... but was [...] 表示 Elasticsearch 在构建 OIDC 授权码交换请求时， … - [无法解析字符串声明 claimName - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-parse-string-claim-claimname-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.x-8.x 1. 错误异常的基本描述 # cannot parse string claim [claimName] 表示 Elasticsearch 在解析 JWT / OIDC 令牌中的某个声明（claim）时，期望该声明的值为字符串或字符串数组，但实际读取到的数据类型与之不符，导致解析失败并抛出 ElasticsearchSecurityException。 该异常通常出 … - [无法解析或验证 ID Token - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-or-validate-the-id-token-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.x-8.x 1. 错误异常的基本描述 # Failed to parse or validate the ID Token 表示 Elasticsearch 已收到 IdP 返回的 ID Token，但在解析、签名校验、声明校验或 nonce 校验阶段失败。 常见现象 # 用户经由 OIDC 登录时失败，认证流程回调后直接报错。 日志里可能先看到 JWK 刷新尝试，随后仍然 … - [无法解析日期声明 claimName - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-parse-date-claim-claimname-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.x-8.x 1. 错误异常的基本描述 # cannot parse date claim [claimName] 表示 Elasticsearch 在 OIDC 或 JWT 认证流程中，已经从 ID Token、Access Token 或 UserInfo 端点获取到了指定声明（claim），但该声明的值无法被解析为合法的日期时间类型， … - [注册表不匹配 - 期望 AutoDateHistogramAggregationSupplier 却返回了其他实现 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/registry-miss-match-expected-autodatehistogramaggregationsupplier-found-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.x-8.x 1. 错误异常的基本描述 # Registry miss-match - expected AutoDateHistogramAggregationSupplier; found [...] 表示 Elasticsearch 已经进入聚合构建阶段，并尝试从 ValuesSourceRegistry … - [注册表不匹配 - 期望 BoxplotAggregatorSupplier 却返回了其他实现 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/registry-miss-match-expected-boxplotaggregatorsupplier-found-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.x-8.x 1. 错误异常的基本描述 # Registry miss-match - expected BoxplotAggregatorSupplier; found [...] 表示 Elasticsearch 已经进入聚合构建阶段，并尝试从 ValuesSourceRegistry 取得 BoxplotAggregationBuilder 所需的聚合器实现，但实际返回对象 … - [注册表不匹配 - 期望 CardinalityAggregatorSupplier 却返回了其他实现 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/registry-miss-match-expected-cardinalityaggregatorsupplier-found-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.x-8.x 1. 错误异常的基本描述 # Registry miss-match - expected CardinalityAggregatorSupplier; found [...] 表示 Elasticsearch 已经进入聚合构建阶段，并尝试从 ValuesSourceRegistry 取得 CardinalityAggregationBuilder 所需的聚合器实 … - [注册表不匹配 - 期望 DateHistogramAggregationSupplier 却返回了其他实现 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/registry-miss-match-expected-datehistogramaggregationsupplier-found-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.x-8.x 1. 错误异常的基本描述 # Registry miss-match - expected DateHistogramAggregationSupplier; found [...] 表示 Elasticsearch 已经进入聚合构建阶段，并尝试从 ValuesSourceRegistry 取得 DateHistogramAggregationBuilder 所需的 … - [注册表不匹配 - 期望 ExtendedStatsAggregatorProvider 却返回了其他实现 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/registry-miss-match-expected-extendedstatsaggregatorprovider-found-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.x-8.x 1. 错误异常的基本描述 # Registry miss-match - expected ExtendedStatsAggregatorProvider; found [...] 表示 Elasticsearch 已经进入聚合构建阶段，并尝试从 ValuesSourceRegistry 取得 ExtendedStatsAggregationBuilder 所需的聚 … - [注册表不匹配 - 期望 HistogramAggregatorSupplier 却返回了其他实现 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/registry-miss-match-expected-histogramaggregatorsupplier-found-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.x-8.x 1. 错误异常的基本描述 # Registry miss-match - expected HistogramAggregatorSupplier; found [...] 表示 Elasticsearch 已经进入聚合构建阶段，并尝试从 ValuesSourceRegistry 取得 HistogramAggregationBuilder 所需的聚合器实现，但实际 … - [注册表不匹配 - 期望 IpRangeAggregatorSupplier 却返回了其他实现 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/registry-miss-match-expected-iprangeaggregatorsupplier-found-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.x-8.x 1. 错误异常的基本描述 # Registry miss-match - expected IpRangeAggregatorSupplier; found [...] 表示 Elasticsearch 已经进入聚合构建阶段，并尝试从 ValuesSourceRegistry 取得 IpRangeAggregationBuilder 所需的聚合器实现，但实际返回对象 … - [注册表不匹配 - 期望 MedianAbsoluteDeviationAggregatorSupplier 却返回了其他实现 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/registry-miss-match-expected-medianabsolutedeviationaggregatorsupplier-found-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.x-8.x 1. 错误异常的基本描述 # Registry miss-match - expected MedianAbsoluteDeviationAggregatorSupplier; found [...] 表示 Elasticsearch 已经进入聚合构建阶段，并尝试从 ValuesSourceRegistry … - [注册表不匹配 - 期望 MetricAggregatorSupplier 却返回了其他实现 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/registry-miss-match-expected-metricaggregatorsupplier-found-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.x-8.x 1. 错误异常的基本描述 # Registry miss-match - expected MetricAggregatorSupplier; found [...] 表示 Elasticsearch 已经进入聚合构建阶段，并尝试从 ValuesSourceRegistry 取得某个依赖 MetricAggregatorSupplier 的指标聚合实现，但实际返回对 … - [注册表不匹配 - 期望 MinMaxAggregatorSupplier 却返回了其他实现 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/registry-miss-match-expected-minmaxaggregatorsupplier-found-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.x-8.x 1. 错误异常的基本描述 # Registry miss-match - expected MinMaxAggregatorSupplier; found [...] 表示 Elasticsearch 已经进入聚合构建阶段，并尝试从 ValuesSourceRegistry 取得 MaxAggregationBuilder … - [注册表不匹配 - 期望 MissingAggregatorSupplier 却返回了其他实现 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/registry-miss-match-expected-missingaggregatorsupplier-found-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.x-8.x 1. 错误异常的基本描述 # Registry miss-match - expected MissingAggregatorSupplier; found [...] 表示 Elasticsearch 已经进入聚合构建阶段，并尝试从 ValuesSourceRegistry 取得 MissingAggregationBuilder 所需的聚合器实现，但实际返回对象 … - [注册表不匹配 - 期望 PercentilesAggregatorSupplier 却返回了其他实现 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/registry-miss-match-expected-percentilesaggregatorsupplier-found-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.x-8.x 1. 错误异常的基本描述 # Registry miss-match - expected PercentilesAggregatorSupplier; found [...] 表示 Elasticsearch 已经进入聚合构建阶段，并尝试从 ValuesSourceRegistry 取得 PercentilesAggregationBuilder 所需的聚合器实 … - [注册表不匹配 - 期望 RangeAggregatorSupplier 却返回了其他实现 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/registry-miss-match-expected-rangeaggregatorsupplier-found-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.x-8.x 1. 错误异常的基本描述 # Registry miss-match - expected RangeAggregatorSupplier; found [...] 表示 Elasticsearch 已经进入聚合构建阶段，并尝试从 ValuesSourceRegistry 取得 aggregationTypeName 所需的聚合器实现， … - [注册表不匹配 - 期望 RareTermsAggregatorSupplier 却返回了其他实现 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/registry-miss-match-expected-raretermsaggregatorsupplier-found-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.x-8.x 1. 错误异常的基本描述 # Registry miss-match - expected RareTermsAggregatorSupplier; found [...] 表示 Elasticsearch 已经进入聚合构建阶段，并尝试从 ValuesSourceRegistry 取得 RareTermsAggregationBuilder 所需的聚合器实现，但实际 … - [注册表不匹配 - 期望 SignificantTermsAggregatorSupplier 却返回了其他实现 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/registry-miss-match-expected-significanttermsaggregatorsupplier-found-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.x-8.x 1. 错误异常的基本描述 # Registry miss-match - expected SignificantTermsAggregatorSupplier; found [...] 表示 Elasticsearch 已经进入聚合构建阶段，并尝试从 ValuesSourceRegistry … - [注册表不匹配 - 期望 StringStatsAggregatorSupplier 却返回了其他实现 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/registry-miss-match-expected-stringstatsaggregatorsupplier-found-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.x-8.x 1. 错误异常的基本描述 # Registry miss-match - expected StringStatsAggregatorSupplier; found [...] 表示 Elasticsearch 已经进入聚合构建阶段，并尝试从 ValuesSourceRegistry 取得 StringStatsAggregationBuilder 所需的聚合器实 … - [注册表不匹配 - 期望 TermsAggregatorSupplier 却返回了其他实现 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/registry-miss-match-expected-termsaggregatorsupplier-found-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.x-8.x 1. 错误异常的基本描述 # Registry miss-match - expected TermsAggregatorSupplier; found [...] 表示 Elasticsearch 已经进入聚合构建阶段，并尝试从 ValuesSourceRegistry 取得 TermsAggregationBuilder 所需的聚合器实现， … - [注册表不匹配 - 期望 ValueCountAggregatorSupplier 却返回了其他实现 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/registry-miss-match-expected-valuecountaggregatorsupplier-found-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.x-8.x 1. 错误异常的基本描述 # Registry miss-match - expected ValueCountAggregatorSupplier; found [...] 表示 Elasticsearch 已经进入聚合构建阶段，并尝试从 ValuesSourceRegistry 取得 ValueCountAggregationBuilder 所需的聚合器实现，但 … - [缺少必需的字符串声明 claimName - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/missing-required-string-claim-claimname-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.x-8.x 1. 错误说明 # missing required string claim [claimName] 表示 Elasticsearch 在安全认证流程中，期望从 OIDC Token、JWT 或 UserInfo 端点获取某个特定的字符串型声明（claim），但实际拿到的内容为空、类型不匹配，或该字段根本不存在，导致后续的用户映射（user mapping）或角色 … - [缺少必需的日期声明 claimName - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/missing-required-date-claim-claimname-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.x-8.x 涉及组件： OpenID Connect Realm、JWT Realm、Elasticsearch 安全模块 1. 错误异常的基本描述 # missing required date claim [claimName] 是 Elasticsearch 在安全认证阶段抛出的异常，表示在解析 JWT / OIDC Token 或 UserInfo 时，某个被标记为必需 … - [获取存储文件元数据失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-get-store-file-metadata-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.x-8.x 1. 错误异常的基本描述 # Failed to get store file metadata 表示快照流程已经拿到了当前分片的 IndexCommit，但在读取该提交对应的本地 store 元数据时失败。 这说明问题发生在“从本地分片读取待快照文件信息”这一步，还没有进入远端仓库上传阶段。 常见现象 # 某个分片快照失败，但仓库本身可能仍然可访问。 日志中出 … - [获取已存在用户失败，跳过用户导入 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-get-users-that-already-exist-skipping-user-import-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.x-8.x 1. 错误异常的基本描述 # failed to get users that already exist; skipping user import 表示导入流程已经读到了本地用户和角色映射文件，但在查询目标集群现有用户列表时失败，因此跳过后续用户导入。 它强调的是“导入前的冲突检查失败”，而不是“用户文件格式错误”。 常见现象 # 用户迁移工具运行后没有导入 … - [获取已存在角色失败，跳过角色导入 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-get-roles-that-already-exist-skipping-role-import-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.x-8.x 1. 错误异常的基本描述 # failed to get roles that already exist; skipping role import 表示导入工具已经成功解析了本地角色定义文件，但在连接目标集群查询“哪些角色已经存在”这一步失败，因此放弃继续导入角色。 这意味着问题不一定在角色文件本身，更可能出在访问目标集群、认证授权或安全配置链路上。 … - [解析 HTTPS URI 失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-https-uri-uristring-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.17-8.9 1. 错误异常的基本描述 # Failed to parse HTTPS URI [uriString]. 表示 Elasticsearch 在读取某个要求为 HTTPS 的配置项时，尝试将字符串转换成 URI 对象失败。该错误通常出现在安全相关配置中，例如 OpenID Connect、JWT、SAML、远程集群元数据地址等需要 HTTPS URL 的场景。 常 … - [解析 License 失败，未提供 Content-Type - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-license-no-content-type-provided-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.x 1. 错误异常的基本描述 # failed to parse license - no content-type provided 表示 Elasticsearch 已经接收到了 License 的字节内容，但无法判断应按哪种 XContent 格式去解析（如 JSON、YAML 等），因此解析器直接抛出异常，拒绝继续处理。 该错误通常发生在 License 上传、 … - [解析 licenses 失败，预期起始对象 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-licenses-expected-start-object-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.x 1. 错误异常的基本描述 # failed to parse licenses expected start object 表示 Elasticsearch 在解析 License 内容时，期望输入是一个 JSON 对象（即以 { 开头），但实际收到的数据顶层结构不符合要求，导致解析器直接抛出异常。 该错误通常发生在 License 上传、 … - [解析 mapping definition 失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-mapping-definition-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.x 1. 错误异常的基本描述 # failed to parse mapping definition 表示 Elasticsearch 在把 mapping 源文本解析成有序 Map 时发生异常，因此后续的字段提取和 mapping 构建无法继续。该错误属于 MapperParsingException 的一种，通常出现在创建索引、更新 mapping 或安装索引模板 … - [解析 mapping 失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-mapping-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.x 1. 错误异常的基本描述 # Failed to parse mapping: {} 表示 Elasticsearch 在将请求中的 mappings 应用到索引模板或索引构建器时失败。与 failed to parse mapping definition 相比，这个错误更靠近实际的 putMapping 调用阶段，意味着 JSON 已经成功解析为对象，但在将其转 … - [访问令牌验证失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-verify-access-token-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.x-8.x 1. 错误异常的基本描述 # failed to verify access token 是 Elasticsearch 在使用 OpenID Connect（OIDC）进行身份认证时，对访问令牌（Access Token）进行校验失败所抛出的异常。该错误通常发生在 Elasticsearch 尝试根据 OIDC 规范验证 Access Token 的签名、有效期或 … - [访问令牌验证失败，ID Token 中缺少 at_hash 声明 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-verify-access-token-id-token-doesn-t-contain-at-hash-claim-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.x-8.x 1. 错误异常的基本描述 # Failed to verify access token. ID Token doesn't contain at_hash claim 表示 Elasticsearch 在 OIDC（OpenID Connect）认证流程中，尝试对 Access Token 进行完整性校验时失败。根据 OIDC 规范，at_hash（Access … - [远程 JWK Set 获取失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-retrieve-remote-jwk-set-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.17-8.9 1. 错误说明 # Failed to retrieve remote JWK set. 表示 Elasticsearch 在通过 OpenID Connect（OIDC）或 JWT 身份认证流程校验令牌签名时，无法从配置的远程 JWK Set 端点（jwks_uri）成功获取公钥集合。 Elasticsearch 依赖 JWK Set 中的公钥来验证 JWT 的 … - [远程 JWK Set 获取失败，请求已取消 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-retrieve-remote-jwk-set-request-was-cancelled-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.17-8.9 1. 错误异常的基本描述 # Failed to retrieve remote JWK set. Request was cancelled. 表示 Elasticsearch 在使用 OpenID Connect（OIDC）认证方式时，向配置的 opendj.jwkset_path 或 oidc.jwkset_path 对应的远程 JWK Set … - [验证失败，使用提供的部分 JWK 仍无法完成验签 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/verify-failed-using-jwksstrength-size-of-jwks-size-provided-jwks-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.x-8.x 1. 错误异常的基本描述 # Verify failed using X of Y provided JWKs. 表示 Elasticsearch 从全部 JWK 中筛出了一部分候选密钥，但逐个尝试后仍然没有一把能成功完成签名验证。 与"所有 JWK 都被过滤掉"不同，这里的筛选阶段已经通过，说明 kid、use、kty 等字段是匹配的，问题出在 … - [验证失败，因为所有提供的 JWK 都被过滤掉了 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/verify-failed-because-all-jwks-size-provided-jwks-were-filtered-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.x-8.x 1. 错误异常的基本描述 # Verify failed because all ... provided JWKs were filtered. 表示 Elasticsearch 在 JWT/JWS 签名验证流程中，虽然成功获取到了 JWK（JSON Web Key）集合，但在按照 kid、算法、用途、密钥长度或曲线等条件进行过滤后，没有任何一把密钥能够满足校验条 … - [验证需要非空 JWK 列表 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/verify-requires-a-non-empty-jwk-list-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.x-8.x 1. 错误异常的基本描述 # Verify requires a non-empty JWK list 表示 Elasticsearch 在执行 JWT 签名验证时，没有拿到任何可用的 JWK（JSON Web Key）。这是 Elasticsearch 安全模块在验签流程入口处做的前置校验：如果传入的 JWK 列表为空，验签根本无法开始，因此直接抛出异常，终止当前 … - [could not parse schedule - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-schedule-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # could not parse schedule: {message} 不是 一个具体的 schedule 错误，而是 Elasticsearch Watcher 在捕获到底层异常之后，用原始异常消息重新包装出来的外层 ElasticsearchParseException。 这意味着真正的根因通常在更内层，例如时间字符串非法、单位错 … - [could not parse schedule invalid value for - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-schedule-invalid-value-for-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # could not parse [schedule_type] schedule. invalid value for [field] 是 Elasticsearch Watcher 在解析 schedule 配置时抛出的异常。此错误表示 Watcher 已经识别出字段名，但字段值本身不符合该字段允许的取值规则。 从日志片段看，这类报错 … - [could not parse schedule invalid weekly times - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-schedule-invalid-weekly-times-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # could not parse [weekly] schedule. invalid weekly times 是 Elasticsearch Watcher 在解析 weekly 类型 schedule（周调度）时抛出的异常。此错误表示 Watcher 已经确认这是 weekly 调度，但在解析周维度的触发时间定义时失败了。 … - [could not parse schedule invalid year times - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-schedule-invalid-year-times-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # could not parse [yearly] schedule. invalid year times 是 Elasticsearch Watcher 在解析 yearly 类型 schedule（年度调度）时抛出的异常。此错误表示 Watcher 已经识别出 yearly 调度类型， … - [daily schedule 的字段时间值无效 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-schedule-invalid-time-value-for-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # could not parse [daily] schedule. invalid time value for field [field] - [token] 是 Elasticsearch Watcher 在解析 daily 类型调度时抛出的异常。该错误表明：解析器已经识别到了字段名（通常是 at）， … - [failed to find type parsed mappingType for name - 未能找到名称对应的字段类型解析器](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-find-type-parsed-mappingtype-for-name-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # failed to find type parsed [mappingType] for [name] 是 Elasticsearch 在映射（mapping）解析阶段抛出的异常。当 Elasticsearch 尝试为某个字段名 name 解析其字段类型 mappingType 时， … - [failed to parse rules expression. expected [..] to be an object but found [...] instead - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-rules-expression-expected-to-be-an-object-but-found-instead-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.x-8.x 1. 错误异常的基本描述 # failed to parse rules expression. expected [..] to be an object but found [...] instead 表示 role mapping 规则里某个具名节点应该是对象，但实际给了别的 JSON 类型。 它与“expected an object”类似，但这里会指出具体 … - [failed to parse rules expression. expected a field value but found [...] instead - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-rules-expression-expected-a-field-value-but-found-instead-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.x-8.x 1. 错误异常的基本描述 # failed to parse rules expression. expected a field value but found [...] instead 表示 Elasticsearch 在解析安全模块的角色映射规则时，已经进入 field 表达式的值区域，但读到的不是允许的字段值类型。 … - [failed to parse rules expression. expected an object but found [...] instead - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-rules-expression-expected-an-object-but-found-instead-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.x-8.x 1. 错误异常的基本描述 # failed to parse rules expression. expected an object but found [...] instead 表示 Elasticsearch 在读取 role mapping 规则时，当前位置必须是一个 JSON 对象，但请求体给了其他类型。 最常见的场景是把 rules 整体写成字符串、数 … - [failed to parse rules expression. field [...] is not allowed within [...] - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-rules-expression-field-is-not-allowed-within-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.x-8.x 1. 错误异常的基本描述 # failed to parse rules expression. field [...] is not allowed within [...] 表示某个规则关键字虽然本身合法，但它出现的位置不合法。 这不是字段拼写错误，而是语法上下文错误。典型例子是把 except 放到了不支持它的对象里，或者把某个关键字放在了错误层级。 … - [failed to parse rules expression. field [...] is not recognised in object [...] - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-rules-expression-field-is-not-recognised-in-object-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.x-8.x 1. 错误异常的基本描述 # failed to parse rules expression. field [...] is not recognised in object [...] 表示 role mapping 规则对象中出现了 Elasticsearch 不认识的字段名。 这类问题大多由拼写错误、大小写错误、旧语法残留或错误复制导致。 常见现象 # … - [failed to parse rules expression. field [...] requires an array - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-rules-expression-field-requires-an-array-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.x-8.x 1. 错误异常的基本描述 # failed to parse rules expression. field [...] requires an array 表示某个规则关键字必须接收数组，但当前请求体提供的不是数组。 这类问题常见于组合规则，例如 all、any 等需要一组子表达式的场景。 常见现象 # role mapping API 返回 400。 报错里 … - [failed to parse rules expression. object [...] contains multiple fields - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-rules-expression-object-contains-multiple-fields-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.x-8.x 1. 错误异常的基本描述 # failed to parse rules expression. object [...] contains multiple fields 表示某个 rules expression 对象中同时出现了多个并列字段，但该对象语法只允许一个入口字段。 在 role mapping grammar 中， … - [failed to parse rules expression. object [...] does not contain any fields - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-rules-expression-object-does-not-contain-any-fields-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.x-8.x 1. 错误异常的基本描述 # failed to parse rules expression. object [...] does not contain any fields 表示某个应该声明规则关键字的对象是空的，解析器读不到任何字段名。 最典型的情况就是把 rules 写成 {}，或者把某个组合表达式数组里的元素写成空对象。 常见现象 # role … - [feature_states 参数值冲突 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/the-feature-states-value-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.12-8.9 1. 错误异常的基本描述 # the feature_states value [none] indicates that no feature states should be restored; but other feature states were requested 表示 restore 请求里的 feature_states 参数自相矛盾。none … - [interval schedule 期待数字或时间字符串 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-schedule-expected-either-a-numeric-value-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # could not parse [interval] schedule. expected either a numeric value (millis) or a string value representing time value (e.g. '5s'), but found [token] 表示 Watcher … - [monthly schedule 的 month times 无法解析 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-schedule-invalid-month-times-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # could not parse [monthly] schedule. invalid month times 表示 Watcher 已经识别出这是一个 monthly 调度，但在继续解析月度触发时间对象时失败了。 2. 为什么会发生这个错误 # 源码显示 MonthlySchedule.parse … - [nested 查询在路径 [nestedPath] 下找不到 nested 对象 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/nested-failed-to-find-nested-object-under-path-nestedpath-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # [nested] failed to find nested object under path [nestedPath] 是 Elasticsearch 在执行 nested 查询、nested 排序或 nested inner hits 时抛出的 QueryShardException。该错误表示查询中指定的 path 在目标索引 … - [schedule 对象里出现了未绑定字段名的 token - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-schedule-unexpected-token-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # could not parse [schedule] schedule. unexpected token [token] 表示 Elasticsearch Watcher 在解析某个 schedule 子对象时，解析器在进入对象体后尚未读到合法的字段名（currentFieldName == null）， … - [watch schedule 为空，未找到调度类型字段 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-schedule-expected-a-schedule-type-field-but-no-fields-were-found-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # could not parse schedule. expected a schedule type field; but no fields were found 是 Elasticsearch Watcher 在解析 watch 的 trigger.schedule 配置时抛出的解析异常。该错误的核心含义是： … - [watch schedule 使用了未知调度类型 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-schedule-for-unknown-schedule-type-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # could not parse schedule for [context]. unknown schedule type [type] 表示 Elasticsearch Watcher 在解析定时触发器的调度配置时，遇到了无法识别的 schedule 类型名。Watcher 的调度解析器内部维护了一个已知类型注册表，当配置中出现的类型 … - [Watcher action 中出现未预期 token - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-action-unexpected-token-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # could not parse [TYPE] action [watchId/actionId]. unexpected token [token] 表示当前 action 解析器读到了不被接受的 JSON token，例如对象、数组、布尔值或空值，而当前位置本来只允许字符串或数字。 从保留片段看，这个异常出现在具体 action 的 … - [Watcher action 中出现未预期的字符串字段 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-action-unexpected-string-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # could not parse [TYPE] action [watchId/actionId]. unexpected string field [field] 表示 Watcher 读取到了一个字符串类型字段，但该字段名不在当前 action 的支持范围内。 从当前源码片段看，这是在 action 逐字段解析字符串值时抛出的异常。 … - [Watcher action 中出现未预期的数字字段 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-action-unexpected-number-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # could not parse [TYPE] action [watchId/actionId]. unexpected number field [field] 表示 Watcher 在解析 action 时读取到了数值字段，但该字段在当前位置并不允许以数字形式出现。 从当前片段可以直接看出，在这段逻辑里只有 timeout 允许以 … - [Watcher action 的 HTTP request template 解析失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-action-failed-parsing-http-request-template-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # could not parse [TYPE] action [watchId/actionId]. failed parsing http request template 表示 Watcher 在解析 webhook action 时，外层动作对象已经识别成功，但其内部的 HttpRequestTemplate 解析失败。 这类异常 … - [Watcher action 的 op_type 值无法解析 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-action-failed-to-parse-op-type-value-for-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.1-7.15 1. 错误异常的基本描述 # could not parse [TYPE] action [watchId/actionId]. failed to parse op_type value for field [field] 表示 Watcher 在读取 op_type 时，连合法枚举都没能解析出来。 这和“op_type 必须是 index 或 create”不 … - [Watcher action 的 op_type 只允许 index 或 create - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-action-op-type-value-for-field-how-to-solve-this-elasticsearch-exception/): 适用版本： Elasticsearch 7.1 – 7.17，8.0 – 8.14（Watcher 功能在 7.x 及以上版本中可用，8.x 中 Watcher 继续支持但部分配置方式有所调整） 1. 错误异常的基本描述 # could not parse [TYPE] action [watchId/actionId]. op_type value for field [field] … - [Watcher action 的索引名值解析失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-action-failed-to-parse-index-name-value-for-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # could not parse [TYPE] action [watchId/actionId]. failed to parse index name value for field [field] 表示 Watcher 在解析 index action 的索引名字段时失败了。 从源码片段看，这里失败点发生在 index = … - [Watcher 缺少合法的触发器类型字段 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-trigger-for-expected-trigger-type-string-field-but-found-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # could not parse trigger for [watchId]. expected trigger type string field; but found [token] 表示 Watcher 进入 trigger 对象后，本来应该先读到一个字段名作为触发器类型，例如 schedule，结果却读到了其他 token。 换 … - [Watcher 触发器主体不是对象 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-trigger-for-expected-trigger-an-object-as-the-trigger-body-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # could not parse trigger [type] for [watchId]. expected trigger an object as the trigger body; but found [token] 表示 Watcher 已经识别出了触发器类型字段，但这个字段后面跟的值不是一个 JSON 对象。 Watcher … - [Watcher 触发器事件上下文字段与类型不匹配 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-trigger-incident-event-context-unexpected-field-for-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # could not parse trigger incident event context. unexpected field [field] for [type] context 表示 Watcher 已经知道当前上下文类型，但在该类型的模板里读到了不允许出现的字段。 日志片段给出的例子非常明确: 当上下文类型是 link … - [Watcher 触发器事件上下文类型未知 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-trigger-incident-event-context-unknown-context-type-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.17 1. 错误异常的基本描述 # could not parse trigger incident event context. unknown context type [type] 表示 Watcher 在解析事件上下文模板时，拿到了一个无法识别的 type 值。 这与“缺少字段”不同: 这里 type 已经存在，但它不在当前代码支持的类型枚举里， … - [Watcher 触发器事件上下文缺少必填字段 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-trigger-incident-event-context-missing-required-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # could not parse trigger incident event context. missing required field [type] 表示 Watcher 在构造触发器事件上下文模板时，发现某个必填字段不存在。根据日志片段，这里最直接的必填字段就是 type。 这类错误通常出现在 Watcher 内部要生成事件上 … - [Watcher 触发器对象结束位置不正确 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-trigger-for-expected-end-object-token-but-found-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # could not parse trigger [type] for [watchId]. expected [END_OBJECT] token; but found [token] 表示 Watcher 已经按某个触发器类型完成了解析，但在该类型对象结尾的位置没有读到预期的 }，而是又遇到了其他 token。 … - [Watcher 触发器类型未知 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-trigger-for-unknown-trigger-type-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # could not parse trigger [type] for [watchId]. unknown trigger type [type] 表示 Watcher 已经找到了触发器类型字段名，但这个类型没有对应的 TriggerEngine 可以解析。 这说明问题不在 JSON 格式，而在字段名语义上: 你写了一个 Watcher … - [yearly schedule 必须是对象或对象数组 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-schedule-expected-either-an-object-or-an-array-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # could not parse [yearly] schedule. expected either an object or an array of objects representing year times; but found [token] instead 是 Elasticsearch Watcher 在解析 yearly … - [从 translog 读取操作失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-read-operation-from-translog-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.x-8.x 1. 错误异常的基本描述 # failed to read operation from translog 表示 Elasticsearch 在执行实时读取（realtime get）时，试图直接从 translog 中恢复最近写入的操作记录，但读取过程失败并抛出了 IOException。 在 Elasticsearch 内部，实时获取文档（get API）的流程 … - [从指定路径读取证书失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-read-certificates-from-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.x-8.x 1. 错误异常的基本描述 # Failed to read certificates from <path> 表示 Elasticsearch 在读取指定证书文件时失败。根据当前页面的源码片段，这段逻辑不仅会在文件不可读时抛错，还会在同一个文件中读到多张证书时直接失败，因为这里明确要求“只能有一张证书”。 常见现象 # … - [启动 operator users 文件监听失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-start-watching-the-operator-users-file-file-toabsolutepath-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.10-8.x 1. 错误异常的基本描述 # Failed to start watching the operator users file [<absolute-path>] 表示 Elasticsearch 在启动 operator users 本地文件监听时失败。这个文件用于判定哪些用户属于 operator user，因此异常会影响操作员权限相关能力的动态生 … - [启动 service_tokens 文件监控失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-start-watching-service-tokens-file-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.13-8.x 1. 错误异常的基本描述 # failed to start watching service_tokens file [path] 表示 Elasticsearch 安全模块在尝试为 service_tokens 文件注册文件变更监控时失败。该文件用于存放服务账户（Service Account）对应的令牌信息，Elasticsearch 通过文件监控机制实现令 … - [启动 users 文件监听失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-start-watching-users-file-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.x 1. 错误异常的基本描述 # failed to start watching users file [<absolute-path>] 表示 Elasticsearch 不是在读取 users 文件内容时失败，而是在向 ResourceWatcherService 注册该文件的监听器时失败。这个异常通常出现在节点启动或安全配置初始化阶段。 常见现象 # … - [启动 users_roles 文件监听失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-start-watching-the-user-roles-file-file-toabsolutepath-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.x 1. 错误异常的基本描述 # failed to start watching the user roles file [<absolute-path>] 表示 Elasticsearch 在为 users_roles 文件启动监听时失败。这个文件负责 file realm 中“用户到角色”的映射，因此异常出现后，角色变更可能无法被自动感知。 … - [无法为 fullName 找到字段类型解析器 mappingType - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-find-type-parsed-mappingtype-for-fullname-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.11-8.x 1. 错误异常的基本描述 # failed to find type parsed [mappingType] for [fullName] 是一个映射解析阶段的 MapperParsingException。该异常发生在 Elasticsearch 处理动态模板（Dynamic Template）并尝试将某个字段定义为 runtime field 时，集群在内部 … - [无法在当前集群状态版本中找到索引 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-find-index-as-current-cluster-state-with-version-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.x-8.x 1. 错误异常的基本描述 # failed to find index as current cluster state with version [...] is stale 看起来像索引不存在，但源码说明它首先是一个“本地节点集群状态过旧”的问题。 当接收请求的节点发现自己的 cluster state version 低于发送方使用的版本时，会记录 trace … - [无法恢复索引 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-restore-index-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.0-8.9 1. 错误异常的基本描述 # cannot restore index [...] because it cannot be upgraded 表示 Elasticsearch 在执行快照恢复前置校验时，尝试验证快照中的索引元数据，但验证失败，最终抛出 SnapshotRestoreException。从源码看，它发生在真正恢复分片数据之前，属于 restore 请 … - [无法找到地理位置字段 fieldName - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-find-geo-field-fieldname-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.x-8.x 1. 错误异常的基本描述 # failed to find geo field [fieldName] 是 Elasticsearch 在执行地理位置查询时抛出的 QueryShardException。该异常发生在查询分片阶段，当协调节点尝试在每个分片上构建 geo 查询时，发现目标字段的映射类型不符合地理查询的要求，或者该字段在当前索引的映射中根本不存在。 … - [无法找到地理位置点字段 fieldName - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-find-geo-point-field-fieldname-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.x-8.x 1. 错误异常的基本描述 # failed to find geo_point field [fieldName] 是 Elasticsearch 在执行地理位置查询时抛出的异常，表示查询所需的 geo_point 类型字段在映射（mapping）中不存在，导致查询无法继续解析。 该异常由 QueryShardException 抛出，发生在查询解析阶段而非数据检索 … - [无法找到字段 fieldName 的类型 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-find-type-for-field-fieldname-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.x-8.x 1. 错误异常的基本描述 # failed to find type for field [fieldName] 是 Elasticsearch 在查询解析阶段抛出的 QueryShardException，表示协调节点在构建查询时调用 context.getFieldType(fieldName) 返回了 null，即该字段在目标索引的 mapping 中不存在， … - [无法找到本地索引元数据 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-find-local-indexmetadata-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.x 1. 错误说明 # failed to find local IndexMetaData 表示 Elasticsearch 节点在启动时或从本地磁盘恢复分片状态时，无法在本地数据目录中找到指定索引的元数据（IndexMetaData）文件，从而主动抛出 ElasticsearchException。 该异常通常发生在节点尝试加载本地分片状态的关键路径上。 … - [无法找到现有事务日志文件 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-find-existing-translog-files-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.x-8.x 1. 错误异常的基本描述 # failed to find existing translog files 表示 Elasticsearch 在处理损坏分片或恢复分片时，尝试读取 translogPath 目录中的现有 translog 文件，但在列目录阶段就抛出了 IOException。 这不是查询层错误，而是分片存储层错误。异常通常出现在 translog 工 … - [无法解析 HTTP 响应：headers 中期望头名却读到了别的 token (Could not parse http response expected a header name but found) - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-http-response-expected-a-header-name-but-found-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # could not parse http response. expected a header name but found [token] instead 是 Elasticsearch Watcher 在执行 HTTP 类型的监视器（watch action）时抛出的解析异常。当 Watcher 向某个 HTTP 端点发送请求并接 … - [无法解析 HTTP 响应：出现了意外的 token (Could not parse http response unexpected token) - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-http-response-unexpected-token-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 问题含义 # could not parse http response. unexpected token [token] 表示解析器收到了当前分支不接受的 JSON token。结合附带源码，这既可能发生在响应顶层字段解析时，也可能发生在 headers 内部值解析时。 典型场景包括：顶层把字段写成布尔值或数组；headers 某个 header 值被写成 … - [无法解析 HTTP 响应：出现了未知的字符串字段 (Could not parse http response unknown string field) - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-http-response-unknown-string-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # could not parse http response. unknown string field [field] 表示 Elasticsearch 在解析 Watcher 的 HTTP 响应体时，遇到了顶层对象中不被识别的字符串类型字段。根据源码逻辑，Watcher 的 HTTP 响应解析器在顶层只接受特定的字符串字段 body， … - [无法解析 HTTP 响应：出现了未知的数值字段 (Could not parse http response unknown numeric field) - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-http-response-unknown-numeric-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # could not parse http response. unknown numeric field [field] 是 Elasticsearch Watcher 在执行 HTTP 输入（http input）或 Webhook 动作时抛出的解析异常。当 Watcher 尝试解析某个 HTTP 响应体时，发现响应 JSON 的顶层 … - [无法解析 HTTP 响应：期望字段名却读到了别的 token (Could not parse http response expected a field name but found instead) - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-http-response-expected-a-field-name-but-found-instead-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 问题含义 # could not parse http response. expected a field name but found [token] instead 表示响应解析器正在读取顶层对象，但当前 token 不是字段名。换句话说，响应 JSON 应该是一个标准对象，例如包含 status、body、headers 等字段；现在实际给到了解析器的 … - [无法解析 HTTP 响应：缺少必填的状态码字段 (Could not parse http response missing required numeric field holding the) - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-http-response-missing-required-numeric-field-holding-the-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # could not parse http response. missing required numeric [status] field holding the response's http status code 表示 Elasticsearch 在解析 HTTP 响应 JSON 时，发现其中缺少必填的数值字段 status。该 … - [无法解析 HTTP 请求模板：出现了意外的字符串字段 (Could not parse http request template unexpected string field) - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-http-request-template-unexpected-string-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 问题含义 # could not parse http request template. unexpected string field [field] 表示某个字段名虽然对应的是字符串值，但这个 key 不在请求模板允许的字段集合里。源码片段能明确看到 method、host 属于可接受字段，其他片段中还会包含 scheme、path、body 等固定字 … - [无法解析 HTTP 请求模板：出现了意外的对象字段 (Could not parse http request template unexpected object field) - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-http-request-template-unexpected-object-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 问题含义 # could not parse http request template. unexpected object field [field] 表示请求模板里某个字段被写成了 JSON 对象，但解析器不接受它是对象。根据源码片段，当前分支只允许 auth 字段进入对象解析，并调用 BasicAuth.parse(parser)。 因此，最常见的触发 … - [无法解析 HTTP 请求模板：出现了意外的数字字段 (Could not parse http request template unexpected numeric field) - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-http-request-template-unexpected-numeric-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # could not parse http request template. unexpected numeric field [field] 是 Elasticsearch Watcher 组件在解析 HTTP 请求模板（HTTP Request Template）时抛出的异常。该错误表示：在解析 Watcher 的 actions … - [无法解析 HTTP 请求模板：字段 token 类型不匹配 (Could not parse http request template unexpected token for field) - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-http-request-template-unexpected-token-for-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 问题含义 # could not parse http request template. unexpected token [token] for field [field] 表示字段名是已知的，但字段值的 JSON token 类型不对。解析器会按字段名决定接收字符串、数字还是对象；一旦实际 token 不匹配，就会抛出这个异常。 … - [无法解析 HTTP 请求模板：字段值解析失败 (Could not parse http request template could not parse value for field) - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-http-request-template-could-not-parse-value-for-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 问题含义 # could not parse http request template. could not parse value for [field] field 表示 Watcher 在反序列化 HTTP 请求模板时，已经定位到具体字段，但该字段的值无法被 TextTemplate.parse 正常解析。它常见于 webhook、http … - [无法解析 HTTP 请求模板：端口值不合法 (Could not parse http request template wrong port for) - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-http-request-template-wrong-port-for-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # could not parse http request template. wrong port for [port] 表示 Elasticsearch Watcher 在解析 HTTP 请求模板时，发现 port 字段的值不合法。根据源码逻辑，端口号必须是正整数（大于 0），否则会在模板解析阶段直接抛出异常，导致整个 Watcher … - [无法解析 HTTP 请求模板：缺少必填字符串字段 (Could not parse http request template missing required string field) - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-http-request-template-missing-required-string-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # could not parse http request template. missing required [host] string field 表示 Elasticsearch 在解析 Watcher 的 HTTP 请求模板时，发现必填的字符串字段缺失。根据源码逻辑，解析器在构建 HttpRequest … - [无法解析 HTTP 请求：出现了意外的字符串字段 (Could not parse http request unexpected string field) - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-http-request-unexpected-string-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误含义 # could not parse http request. unexpected string field [field] 表示 Elasticsearch 在解析 HTTP 请求对象时，发现了一个不被允许的字符串类型字段。 该异常通常出现在以下场景中： 配置 Watcher 的 HTTP 输入/Webhook 动作时，请求体中的字段名拼写错 … - [无法解析 HTTP 请求：出现了意外的对象字段 (Could not parse http request unexpected object field) - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-http-request-unexpected-object-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 问题含义 # could not parse http request. unexpected object field [field] 表示请求对象里某个字段被写成了 JSON 对象，但当前解析器只接受少数字段为对象。根据源码片段，headers 和 params 可以是对象，其余字段一旦给对象就会报错。 常见误用是把 body 直接写成对象， … - [无法解析 HTTP 请求：出现了意外的数字字段 (Could not parse http request unexpected numeric field) - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-http-request-unexpected-numeric-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # could not parse http request. unexpected numeric field [field] 表示 Elasticsearch 在解析 HTTP 请求对象（常见于 Watcher 的 Webhook 配置、_watcher API 的 HTTP 输入/执行动作中）时，遇到了不该以数值形式出现的字段。 … - [无法解析模糊度中的 low 和 high 距离值 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-find-low-and-high-distance-values-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # failed to find low and high distance values 表示 Elasticsearch 在解析模糊查询（fuzziness）的 AUTO 模式自定义阈值时，无法从传入的字符串中提取出合法的 low 和 high 两个整数值。该异常属于 parse_exception，通常在查询 DSL 解析阶段抛出， … - [无法读取 users 文件 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-read-users-file-path-toabsolutepath-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.x 1. 错误异常的基本描述 # could not read users file [<absolute-path>] 表示 Elasticsearch 在加载 file realm 用户文件时，Files.readAllLines(...) 这一步就失败了。这里的 path.toAbsolutePath() 不是字面路径名，而是源码中的变量占位，实际日志 … - [无法读取角色映射文件 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-read-realm-realmtype-realmname-role-mappings-file-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.x 1. 错误异常的基本描述 # could not read realm [realmType/realmName] role mappings file 表示 Elasticsearch 在加载某个 realm 的本地角色映射文件时失败。这里最关键的配置项是 files.role_mapping，常见于 LDAP、Active Directory、PKI … - [无法读取证书 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-read-certificate-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.x-8.x 1. 错误异常的基本描述 # Cannot read certificate 不是网络连接错误，也不是证书文件路径错误。根据当前页面保留的源码，这个异常出现在 Elasticsearch 对 X509Certificate 调用 getEncoded() 时，说明系统已经拿到了证书对象，但在把它编码成字节数组时失败了。 常见现象 # 问题常出现在安全配置导出、证 … - [未找到指定类型字段 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-find-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.x-8.x 1. 错误异常的基本描述 # failed to find <validContentTypes> field [fieldName] 是 Elasticsearch 在查询构建阶段抛出的一类通用字段查找异常。它表示当前查询要求某种特定类型的字段（如 keyword、geo_point、date 等），但在目标索引的 mapping … - [未知的 Watcher action 类型 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-action-unknown-action-type-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # could not parse action [watchId/actionId]. unknown action type [field] 表示 Watcher 在解析某个 action 时，已经读到了一个看起来像动作类型的字段名，但这个字段并没有在 actionRegistry 中注册。 … - [未能找到 minimum_should_match 字段 minimumShouldMatchField - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-find-minimum-should-match-field-minimumshouldmatchfield-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.x-8.x 1. 错误异常的基本描述 # failed to find minimum_should_match field [minimumShouldMatchField] 是 Elasticsearch 在执行查询阶段抛出的 QueryShardException。该错误表示查询配置中通过 minimum_should_match_field 指定了一个字段，期望从该字段 … - [未能找到 queryFieldType 对应字段 fieldName - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-find-queryfieldtype-field-fieldname-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.x-8.x 1. 错误异常的基本描述 # failed to find <queryFieldType> field [fieldName] 是 Elasticsearch 在执行查询阶段（QueryShardException）抛出的异常，表示当前查询依赖某一特定类型的字段，但在目标索引的 mapping 中无法找到名为 fieldName 的字段，或其类型与查询 … - [未能找到地理位置形状字段 fieldName - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-find-geo-shape-field-fieldname-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.x 1. 错误异常的基本描述 # failed to find geo_shape field [fieldName] 是 Elasticsearch 在执行 geo_shape 类型查询时抛出的 QueryShardException。该错误表示查询中引用的字段在目标索引的 mapping 中不存在，或者该字段的类型不是 geo_shape。 常见现象 # … - [查询解析失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-query-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.x-8.x 1. 错误异常的基本描述 # failed to parse [<query>] query. [<message>] 表示 Elasticsearch 在解析某个查询对象时，底层解析过程已经失败，于是把原始错误消息包装成统一的 parse_exception 再抛出。 从附录源码可见， … - [查询解析失败，query 已重复定义 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-query-query-is-already-defined-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.x-8.x 1. 错误异常的基本描述 # failed to parse [query] query. [query] is already defined. 表示同一个查询对象中，query 字段已经出现过一次，又被再次定义。 附录源码显示，解析器会先判断 if (query != null)，只要已经解析过一个 query，第二次再遇到 query 就直接报错。这种错误经常 … - [查询解析失败，query_string 语法错误 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-query-this-querystring-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.x-8.x 1. 错误异常的基本描述 # Failed to parse query [queryString] 表示 Elasticsearch 已经把 query_string 交给 Lucene 查询解析器处理，但 Lucene 在语法层面失败了，于是包装成 QueryShardException 返回。 … - [查询解析失败，不支持该数组字段 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-query-array-is-not-supported-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.x-8.x 1. 错误异常的基本描述 # failed to parse [query] query. array [field] is not supported 表示当前查询解析器遇到了数组类型字段，但这个字段在该位置并不允许是数组。 附录代码来自函数评分查询解析流程。只有特定字段允许数组，例如专门的函数列表；如果把其他字段写成数组，就会触发这条错误。 2. 常见原因 # … - [查询解析失败，出现未预期字段 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-query-unexpected-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.x-8.x 1. 错误异常的基本描述 # failed to parse [query] query. unexpected field [field] 表示当前查询解析器已经识别并消费了第一个目标字段，后面又遇到第二个不该出现的字段，因此直接报错。 附录源码里，当 fieldName == null 时会把当前字段作为目标字段；一旦 fieldName 已经存在，再遇到其他字 … - [查询解析失败，字段不受支持 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-query-field-is-not-supported-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.x-8.x 1. 错误异常的基本描述 # failed to parse [query] query. field [field] is not supported 表示 Elasticsearch 读取到一个字段名，但这个字段不在当前查询解析器允许列表中。 附录片段来自函数评分查询解析逻辑。它会逐个识别支持的字段；一旦命中未知字段，就会抛 ParsingException。 … - [查询解析失败，未提供网格 ID - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-query-grid-id-not-provided-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.x-8.x 1. 错误异常的基本描述 # failed to parse [query] query. grid id not provided 表示 Elasticsearch 已经知道要按哪种网格类型解析，但没有拿到具体的 grid_id，因此无法定位目标网格单元。 源码显示该异常发生在 grid != null 之后，因此这里缺的是网格值，不是网格类型。 2. … - [查询解析失败，未提供网格名称 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-query-grid-name-not-provided-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.3-8.9（geo_grid 查询自 8.3 版本引入） 1. 错误异常的基本描述 # failed to parse [query] query. grid name not provided 是 Elasticsearch 在解析 geo_grid 查询时抛出的 ElasticsearchParseException。该错误表示请求中缺少 grid 字段，即未指定要使用哪种 … - [查询解析失败，未提供边界框 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-query-bounding-box-not-provided-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.x-8.x 1. 错误异常的基本描述 # failed to parse [query] query. bounding box not provided 表示 Elasticsearch 已经识别到这是一个边界框查询，但请求里没有真正提供边界框对象，因此无法构造 GeoBoundingBoxQueryBuilder。 源码中只有在 bbox == null 时才会抛出这条异 … - [查询解析失败，未知 type 值 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-query-type-unknown-type-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.x-8.x 1. 错误异常的基本描述 # failed to parse [query] query type [value]. unknown type. 表示当前查询支持 type 参数，但你传入的值不在它允许的枚举集合中。 源码里会遍历可接受的类型枚举；如果遍历结束后 type == null，就抛出这条异常。因此这是一个很典型的参数取值校验错误。 2. 常见原因 # … - [查询解析失败，网格名称无效 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-query-invalid-grid-name-name-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.x-8.x 1. 错误异常的基本描述 # failed to parse [query] query. Invalid grid name [name] 表示查询里确实提供了 grid，但该值不是 Elasticsearch 当前支持的网格类型。 从源码看，这里只接受 geotile 和 geohash。只要传入其他字符串，就会立即抛出解析异常。 2. 常见原因 # 拼写错 … - [监听配置文件失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-watch-file-from-setting-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.x-8.x 1. 错误异常的基本描述 # Failed to watch file [<path>] (from setting [<key>]) 表示 Elasticsearch 已经根据某个配置项解析出了目标文件路径，但在把该文件加入资源监听服务时失败。与单个 users 或 users_roles 文件不同，这个异常是更通用的“配置项对应文件监听失 … - [解析 action 失败：出现意外的 token - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-action-unexpected-token-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.x 1. 错误说明 # 报错 failed to parse [<type>] action [<watch_id>/<action_id>]. unexpected token [<token>/<field>] 表示 Elasticsearch 在解析 action 配置时， … - [解析 action 失败：出现意外的字符串字段 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-action-unexpected-string-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.x 1. 错误说明 # 报错 failed to parse [<type>] action [<watch_id>/<action_id>]. unexpected string field [<field>] 表示 Elasticsearch 在解析 action 配置时，读到了一个不在允许列表里的字符串字段名。 附录 … - [解析 action 失败：字段本应为字符串却收到其他类型 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-action-expected-to-be-of-type-string-but-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.x 1. 错误说明 # 报错 failed to parse [<type>] action [<watch_id>/<action_id>]. expected [<field>] to be of type string; but found [<token>] instead … - [解析 action 失败：无法解析 fields 字段 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-action-failed-to-parse-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.x 1. 错误说明 # 报错 failed to parse [<type>] action [<watch_id>/<action_id>]. failed to parse [fields] field 表示 Elasticsearch 在解析某个 action 的 fields 配置时失败了。 从附录代码可以看到， … - [解析 action 失败：未知的日志级别 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-action-unknown-logging-level-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.x 1. 错误说明 # 报错 failed to parse [<type>] action [<watch_id>/<action_id>]. unknown logging level [<value>] 表示 Elasticsearch 在解析 logging action 时，尝试把 level 字段转换成内部日志 … - [解析 action 失败：缺少必填字段 message - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-action-missing-required-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.x 1. 错误说明 # 报错 failed to parse [<type>] action [<watch_id>/<action_id>]. missing required [message] field 表示 Watcher 在解析某个 action 时，没有找到必填的 message 字段。 附录代码已经表明， … - [解析 Watcher action 失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-action-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # could not parse [TYPE] action [watchId/actionId] 表示 Watcher 已经识别出某个具体 action 类型，但在继续解析该 action 的字段时失败了。 从当前页面保留的源码看，这个异常不是最原始的报错，而是对内部 IllegalArgumentException 的二次包装。当前 … - [解析角色 transient metadata 失败：应为对象却收到其他类型 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-transient-metadata-for-role-expected-but-got-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.x 1. 错误说明 # failed to parse transient metadata for role [<role>]. expected START_OBJECT but got <token> 是 Elasticsearch 在安全角色（Role）解析阶段抛出的解析异常。该错误表示角色定义中的 transient_metadata … - [解析角色失败：应为对象却收到其他类型 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-role-expected-an-object-but-found-instead-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.x 1. 错误说明 # failed to parse role [<role>]. expected an object but found [<token>] instead 表示 Elasticsearch 在解析角色定义时，期望读到一个 JSON 对象（{ 开头），但实际收到的是其他类型的 token。 … - [解析角色失败：角色内部字段格式不合法 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-role-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.x 1. 错误说明 # 报错 failed to parse role [<role>] 本身通常不是最原始的错误，而是 Elasticsearch 在解析角色内部字段时，对底层 ElasticsearchParseException 的再次包装。 从日志上下文可以看到，这个异常会把具体角色名附加到原始异常上，方便你知道是哪个角色定义出错。因此真正的根因往往 … - [解析角色时出现意外字段 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-role-unexpected-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.x 1. 错误说明 # failed to parse role [<role_name>]. unexpected field [<field_name>] 是 Elasticsearch 安全模块在解析角色定义 JSON 时抛出的异常。当角色定义中包含当前版本不支持、无法识别或放错层级的字段名时，解析器无法继续处理，从而触发此错误。 该错误通 … - [解析角色的应用权限失败：字段值必须是对象数组 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-application-privileges-for-role-expected-field-value-to-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.x 1. 错误说明 # 报错 failed to parse application privileges for role [<role>]. expected field [<field>] value to be an array of objects; but found an array element of type … - [解析角色的应用权限失败：字段值必须是数组 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-application-privileges-for-role-expected-field-value-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.x 1. 错误说明 # 报错 failed to parse application privileges for role [<role>]. expected field [<field>] value to be an array; but found [<token>] instead 表示角色定义中的应用权限字段类型不正确。 … - [解析角色的应用权限失败：缺少必需字段 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-application-privileges-for-role-missing-required-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.x 1. 错误说明 # 报错 failed to parse application privileges for role [<role>]. missing required [<field>] field 表示 Elasticsearch 在解析角色中的 applications 权限配置时，发现某个应用权限对象缺少必填字段。 从日志上下文 … - [解析角色索引权限失败：字段不能为空数组 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-indices-privileges-for-role-cannot-be-an-empty-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.x 1. 错误说明 # 报错 failed to parse indices privileges for role [<role>]. [<field>] cannot be an empty array 表示 Elasticsearch 在解析角色的索引权限时，发现某个本应包含至少一个值的字段被配置成了空数组。 从附录代码可以看到，解析器允许 … - [解析角色索引权限失败：字段值必须是数组 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-indices-privileges-for-role-expected-field-value-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.x 1. 错误说明 # 报错 failed to parse indices privileges for role [<role>]. expected field [<field>] value to be an array; but found [<token>] instead 表示角色定义中的 indices 权限块，在当前 … - [解析角色索引权限失败：数组元素必须是对象 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-indices-privileges-for-role-expected-field-value-to-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.x 1. 错误说明 # 报错 failed to parse indices privileges for role [<role>]. expected field [<field>] value to be an array of objects; but found an array element of type … - [解析角色索引权限失败：期望特定 token 却收到其他内容 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-indices-privileges-for-role-expected-or-but-got-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.x 1. 错误说明 # 报错 failed to parse indices privileges for role [<role>]. expected <token1> or <token2> but got <token3> 表示 Elasticsearch 在解析索引权限对象内部结构时， … - [解析角色索引权限失败：缺少必填字段 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-indices-privileges-for-role-missing-required-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.x 1. 错误说明 # 报错 failed to parse indices privileges for role [<role>]. missing required [<field>] field 表示单个索引权限对象里缺少 Elasticsearch 解析所必需的字段。 从附录可以看到，解析器至少会检查 names … - [解析角色索引权限失败：设置 except 时必须同时设置 grant - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-indices-privileges-for-role-requires-if-is-given-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.x 1. 错误说明 # 报错 failed to parse indices privileges for role [<role>]. <field1> requires <field2> if <field3> is given 表示字段级权限配置存在依赖关系：你设置了排除字段，但没有提供允许字段集合。 从附录逻辑可 … - [请求的功能状态不存在于快照中 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/requested-feature-states-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.12-8.9 1. 错误异常的基本描述 # requested feature states [...] are not present in snapshot 表示你在 restore 请求中显式指定了若干 feature_states，但 Elasticsearch 读取快照元数据后发现，这些 feature state 并不在目标快照里， … - [读取值失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-read-value-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.x-8.x 1. 错误异常的基本描述 # failed to read value 表示 Elasticsearch 在懒加载某个值时，尝试把已保存的字节内容重新解析成对象，但解析过程抛出了 IOException。这个异常通常出现在反序列化阶段，而不是查询或写入阶段。 常见现象 # Elasticsearch 日志中出现 ElasticsearchException: … - [读取全局元数据失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-read-global-metadata-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.x-8.x 1. 错误异常的基本描述 # failed to read global metadata 表示 Elasticsearch 在访问快照仓库时，尝试读取某个快照对应的全局元数据文件（global-* blob）失败。该错误通常发生在执行快照恢复、快照状态查询或仓库验证等操作中。 全局元数据（global metadata）包含集群的持久化设置、索引模板、SLM 策略 … - [读取字段 [fieldName] 的值失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-read-values-for-field-fieldname-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.x-8.x 1. 错误异常的基本描述 # Failed to read values for field [fieldName] 表示 Elasticsearch 在按列读取某个字段的 doc values 时发生了 I/O 失败。该异常通常出现在查询、聚合或排序阶段，当 Elasticsearch 尝试从磁盘读取指定字段的列式存储数据（doc values）时，底层读取操作抛 … - [读取密钥库失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-read-keystore-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.x-8.x 1. 错误异常的基本描述 # Failed to read keystore <path> 表示 Elasticsearch 在读取指定 keystore 时失败。结合日志上下文，这里处理的是 CA keystore，并且源码还会额外检查其中的 key 数量是否符合预期。 这说明问题不只是“文件打不开”，还可能是“keystore 打开了，但内容结构不符 … - [读取搜索请求时遇到未预期的索引选项 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-read-search-request-unexpected-index-option-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # could not read search request. unexpected index option [field] 表示 Elasticsearch 在解析搜索请求里的索引选项时，读到了一个当前代码分支不认识的字段。 从日志上下文可见，这段解析逻辑只接受有限的布尔参数，例如 ignore_unavailable … - [读取私钥失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-read-private-key-from-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.x-8.x 1. 错误异常的基本描述 # Failed to read private key from <path> 表示 Elasticsearch 在读取指定私钥文件时失败。日志片段显示，这段代码会先提示加密 PEM 私钥需要密码，然后再尝试读取；如果在读取、解密或解析阶段失败，就会抛出当前异常。 常见现象 # 证书工具、TLS 启动或 CA 相关流程中 … - [从开源到合规：Easysearch 如何化解 Elasticsearch 的“卡脖子”风险](https://easysearch.cn/knowledge-base/insight/from-open-source-to-compliance-how-easysearch-mitigates-elasticsearch-lock-in-risks/): 一家计划推出数据智能 SaaS 服务的科技公司，在法务评估时被紧急叫停：其核心的 Elasticsearch 引擎一旦用于对外商业服务，可能触发 SSPL 协议条款，导致整个技术栈被迫开源。技术负责人猛然意识到，他们精心构建的数据护城河，底层竟是一道由他人控制闸门的脆弱大坝。 “卡脖子”风险在基础软件领域已从硬件芯片蔓延至开源软件。当一项核心技术及其生态的法律条款、持续供应和演进方向受单一商业实 … - [[auto_create_index] contains [-pattern] which forbids automatic creation of the index - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/auto-create-index-setting-getkey-contains-how-to-solve-this-elasticsearch-exception/): 适用版本： 7-7.15 1. 错误异常的基本描述 # [auto_create_index] contains [-pattern] which forbids automatic creation of the index 表示集群并不是全局关闭了自动建索引，而是 action.auto_create_index 使用了带黑白名单的 pattern 规则，目标索引命中了某个负向规则，因此被 … - [[auto_create_index] is [false] - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/auto-create-index-setting-getkey-is-false-how-to-solve-this-elasticsearch-exception/): 适用版本： 7-8.9 1. 错误异常的基本描述 # [auto_create_index] is [false] 表示 Elasticsearch 在接收到对不存在索引的写请求时，原本可以执行自动建索引，但集群级设置 action.auto_create_index 被明确关闭，因此直接拒绝创建并抛出 IndexNotFoundException。 常见现象 # 首次写入新索引时失败，但 … - [Alias [aliasName] is defined both as an alias and a concrete field - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/alias-aliasmapper-name-is-defined-both-as-an-alias-and-a-concrete-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # Alias [aliasName] is defined both as an alias and a concrete field 是 Elasticsearch 在解析索引映射（mapping）时抛出的 MapperParsingException 异常。该错误的核心含义是：同一个索引中，某个字段别名（field alias）的名 … - [cannot restore partial index - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-restore-partial-index-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.6-7.13 1. 错误异常的基本描述 # cannot restore partial index 出现在快照恢复流程中，表示 Elasticsearch 发现目标索引已经存在，而且当前这个索引被判定为一次不完整恢复留下的 partial index，因此不允许继续直接恢复覆盖。 常见现象 # 恢复快照时返回 SnapshotRestoreException。 集群里已经 … - [composable template [indexPatterns] forbids index auto creation - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/composable-template-template-indexpatterns-forbids-index-auto-creation-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.11-8.9 1. 错误异常的基本描述 # composable template [indexPatterns] forbids index auto creation 表示 Elasticsearch 原本准备为一个不存在的索引执行自动创建，但命中的 composable index template 明确设置了 allow_auto_create: false，因此自动建 … - [could not parse transform for watch unknown transform type - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-transform-for-watch-unknown-transform-type-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # could not parse transform for watch [id]; unknown transform type [type] 是 Elasticsearch Watcher 在解析 transform（转换）时抛出的异常。此错误表示 Watcher 已经读取到 transform 名称， … - [Discovery node must not be null – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/discovery-node-must-not-be-null-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.8-8.9 1. 错误异常的基本描述 # Discovery node must not be null 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口 … - [exception while syncing before creating a snapshot - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/exception-while-syncing-before-creating-a-snapshot-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # exception while syncing before creating a snapshot 表示 Elasticsearch 在为某个分片创建快照前，试图先把 translog 刷盘同步到稳定存储，但 sync() 过程失败了，因此抛出 TranslogException。这类问题更接近底层 IO 或分片本地存储异常，而不是仓 … - [failed to delete snapshots - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-delete-snapshots-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.8-8.9 1. 错误异常的基本描述 # failed to delete snapshots 表示 Elasticsearch 在执行快照删除流程时失败了。它通常不是参数校验错误，而是仓库元数据更新、底层 blob 删除、仓库锁竞争或后端存储异常导致的删除动作未完成。 常见现象 # 调用 DELETE /_snapshot/{repository}/{snapshot} … - [failed to execute snapshot lifecycle policy [policyId] - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-execute-snapshot-lifecycle-policy-policyid-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # failed to execute snapshot lifecycle policy [policyId] 表示 Elasticsearch 已经触发了某个 SLM 策略的执行流程，但最终没有拿到成功生成的快照名称，因此返回执行失败。这通常不是“找不到策略”，而是“策略存在，但实际创建快照过程失败了”。 常见现象 # … - [failed to fetch index version after copying it over - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-fetch-index-version-after-copying-it-over-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # failed to fetch index version after copying it over 出现在分片恢复阶段，表示 Elasticsearch 已经把索引文件复制到目标位置，但在随后读取 Lucene 索引版本时失败了。这通常说明复制后的索引目录状态不完整、文件损坏，或者底层存储读写存在异常。 常见现象 # 分片恢复 … - [failed to get snapshot info - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-get-snapshot-info-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.14-8.9 1. 错误异常的基本描述 # failed to get snapshot info 表示 Elasticsearch 已经定位到某个快照 ID，但在进一步读取这个快照的详情元数据时失败了。它通常出现在列举快照、查询快照详情、恢复前检查快照信息等场景。 常见现象 # GET /_snapshot/{repository}/{snapshot} 返回 500。 … - [HTTP Netty 接收预测器大小配置](https://easysearch.cn/knowledge-base/easysearch_config/http.netty.receive_predictor_size/): 配置项作用 # http.netty.receive_predictor_size 配置项设置 Netty 接收预测器缓冲区的大小。该缓冲区用于预测传入 HTTP 请求的大小，以优化内存分配。 默认值 # 64KB 配置类型 # 静态配置 取值范围 # 字节值（如 64KB, 1MB） 配置格式 # # 默认配置 http.netty.receive_predictor_size: … - [HTTP 警告头大小限制配置](https://easysearch.cn/knowledge-base/easysearch_config/http.max_warning_header_size/): 配置项作用 # http.max_warning_header_size 配置项设置 HTTP 响应中所有警告头的总大小限制，防止过大的警告头消耗过多内存。 默认值 # -1（无限制） 配置类型 # 静态配置 取值范围 # -1 或字节值（如 "1KB", "10MB"） 配置格式 # # 默认配置： … - [index [index] has no active shard copy - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/index-index-has-no-active-shard-copy-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.16-8.9 1. 错误异常的基本描述 # index [index] has no active shard copy 表示 Elasticsearch 在为某个索引选择可执行请求的分片副本时，没有找到任何活动中的 shard copy。它通常出现在搜索、读取或需要访问该索引数据的操作中，本质上是“当前没有任何可用分片副本可以处理这个索引”。 常见现象 # 读请求或搜索请 … - [index is unrecoverable - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/index-is-unrecoverable-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # index is unrecoverable 表示 Elasticsearch 在检查某个分片或索引的本地数据后，判断其已经损坏到无法通过正常恢复流程继续使用。这个错误通常出现在人工诊断工具、损坏修复提示或恢复失败后的进一步检查阶段，含义非常直接: 当前这份本地索引数据已经不可信。 常见现象 # 某个主分片长期无法启动，相关节点日志 … - [not all primary shards of [databases] index are active - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/not-all-primary-shards-of-databases-index-index-are-active-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.17-8.9 1. 错误异常的基本描述 # not all primary shards of [databases] index are active 通常出现在 GeoIP downloader 或相关内部流程检查 .geoip_databases 写索引状态时。它的含义很具体: 该内部索引的所有主分片还没有全部进入 active 状态，所以后续写入或更新流程被阻止。 常见 … - [snapshot [snapName] not found in repository [repoName] - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/snapshot-snapname-not-found-in-repository-reponame-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.12-8.9 1. 错误异常的基本描述 # 当 Elasticsearch 在读取仓库元数据 RepositoryData 时，按快照名称遍历 snapshotIds 仍然找不到目标快照，就会抛出 snapshot [snapName] not found in repository [repoName]。这不是“快照执行失败”的泛化报错，而是一个明确的元数据查找失败异常。 常 … - [snapshot lifecycle policy not found - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/snapshot-lifecycle-policy-not-found-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.4-8.9 1. 错误异常的基本描述 # snapshot lifecycle policy not found 表示 Elasticsearch 在集群状态中的 SnapshotLifecycleMetadata 里找不到指定的 SLM 策略 ID。它通常出现在手动执行策略、查询策略状态、更新策略或删除策略后仍继续引用旧策略名的场景。 常见现象 # … - [start object expected [index metadata identifiers] - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/start-object-expected-index-metadata-identifiers-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.9-7.9 1. 错误异常的基本描述 # start object expected [index metadata identifiers] 是一个元数据解析异常，表示 Elasticsearch 在解析 index_metadata_identifiers 字段时，预期这里应该是一个 JSON object，但实际读到的不是对象结构。这个错误通常出现在读取快照仓库元数据、恢 … - [Unexpected exception when loading repository data - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unexpected-exception-when-loading-repository-data-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.12-8.9 1. 错误异常的基本描述 # Unexpected exception when loading repository data 不是根因异常，而是一个包装异常。意思是 Elasticsearch 在加载仓库元数据时，执行路径里抛出了一个未被更具体处理的异常，最终统一包成 RepositoryException 抛出。 常见现象 # 任何依赖仓库元数据的操作都 … - [不能包含 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/must-not-contain-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 这里的 must not contain 仍然属于快照名称校验，但它针对的是特定非法字符。根据当前页面保留的源码片段，至少包括 ; 和 #，随后还会继续检查前缀字符。也就是说，这篇文章不是在讲查询字符串里的特殊字符，而是在讲 snapshotName 本身不允许包含某些保留字符。 常见现象 # 快照创建请求会在入参校验阶段被拒绝，不 … - [元数据字段上出现未知参数 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unknown-parameter-propname-on-metadata-field-name-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.6-8.9 1. 错误异常的基本描述 # 元数据字段上出现未知参数 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [分析线程池配置](https://easysearch.cn/knowledge-base/easysearch_config/thread_pool.analyze/): 配置项作用 # thread_pool.analyze 相关配置项控制用于执行分析操作的线程池。分析操作包括索引分析请求、字段值分析等功能。该线程池采用固定大小线程池类型。 配置项类型 # 该配置项为静态配置，需要在启动时设置，修改后需要重启节点才能生效。 默认值 # thread_pool.analyze.size: 8 thread_pool.analyze.queue_size: … - [启动转换 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/starting-transform-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.5-7.5 1. 错误异常的基本描述 # 启动转换 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返回 400、404、409、429、500 … - [字段属性值 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/property-value-of-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.7-7.9 1. 错误异常的基本描述 # 字段属性值 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [延迟恢复异常 (delay_recovery_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/delay_recovery_exception/): 为什么这个错误发生 # delay_recovery_exception 表示分片恢复操作被延迟。这通常是一个临时性异常，表示系统决定推迟恢复操作而不是立即失败。 这个错误可能由以下原因引起： 节点过载：目标节点正在进行大量恢复操作，过载可能导致性能问题 并发恢复限制：同时进行的恢复操作数量达到限制 资源紧张：CPU、内存或磁盘 I/O 资源不足 分片迁移中：分片正在迁移， … - [恢复过程中发生文件损坏 – 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/file-corruption-occurred-on-recovery-but-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.2 1. 错误异常的基本描述 # 恢复过程中发生文件损坏 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [找不到指定 ID 的日历：Strings.arrayToCommaDelimitedString(idTokens) – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/no-calendar-with-id-strings-arraytocommadelimitedstring-idtokens-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.1-8.9 1. 错误异常的基本描述 # 找不到指定 ID 的日历：Strings.arrayToCommaDelimitedString(idTokens) 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日 … - [搜索上下文保活检查间隔配置](https://easysearch.cn/knowledge-base/easysearch_config/search.keep_alive_interval/): 配置项作用 # search.keep_alive_interval 配置项控制检查滚动搜索上下文保活状态的间隔时间。系统定期检查滚动上下文是否超过其保活时间（keep_alive），如果超过则清理该上下文。 配置项类型 # 该配置项为动态配置，可以在运行时通过集群设置 API 进行修改。 默认值 # 1m 是否必需 # 可选配置项（有默认值） 取值范围 # 0 ~ 正无穷 配置格式 # … - [无已知主节点 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/no-known-master-nodes-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.17 1. 错误异常的基本描述 # 无已知主节点 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返回 400、404、409、429、500 … - [无效的组名 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/invalid-group-name-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.2-7.9 1. 错误异常的基本描述 # 无效的组名 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法为 elastic/kibana 服务账户创建令牌 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-create-token-for-the-elastic-kibana-service-account-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # 无法为 elastic/kibana 服务账户创建令牌 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能 … - [无法在 indexPath 列出提交记录 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unable-to-list-commits-at-indexpath-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 无法在 indexPath 列出提交记录 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法在非SQL函数上使用 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-use-on-non-sql-function-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.12-8.9 1. 错误异常的基本描述 # 无法在非SQL函数上使用 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法将 SAML 对象编组为 DOM 元素 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-marshall-saml-object-to-dom-element-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.7-8.9 1. 错误异常的基本描述 # 无法将 SAML 对象编组为 DOM 元素 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法添加事件：请求过多 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unable-to-add-the-event-too-many-requests-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.8-8.9 1. 错误异常的基本描述 # 无法添加事件：请求过多 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法确定组合的数据类型 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-determine-datatype-for-combination-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 无法确定组合的数据类型 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法自动解析HTTP发布端口，存在多个绑定地址 – 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-auto-resolve-http-publish-port-multiple-bound-addresses-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # 无法自动解析HTTP发布端口，存在多个绑定地址 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [未捕获任何内容 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/nothing-captured-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 未捕获任何内容 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [查询节点存活状态](https://easysearch.cn/knowledge-base/easysearch_api/get-node-alive-status/): API 状态说明 # 在 Easysearch 中，没有 GET /_nodes/liveness REST API 端点。 实际情况 # 节点存活状态（liveness）功能是通过 Transport 层实现的内部 API，主要用于： 节点之间的内部通信 客户端连接时的节点发现和验证 集群发现和节点验证过程 内部 Action # Action 名 … - [生命周期策略未找到 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/lifecycle-policy-not-found-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 生命周期策略未找到 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [索引检查失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/check-index-failed-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 索引检查失败 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [解析 More Like This 条目时遇到未知字段 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-more-like-this-item-unknown-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.16-8.11 1. 错误异常的基本描述 # failed to parse More Like This item. unknown field [xxx] 是 Elasticsearch 在执行 More Like This（MLT）查询时抛出的解析异常。该错误表示在 more_like_this 查询的单个 item（即 like 数组或 docs 数组中的某一个文档描述 … - [请在之前指定序列by而不是之后 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/please-specify-sequence-by-before-with-not-after-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.8-8.9 1. 错误异常的基本描述 # 请在之前指定序列by而不是之后 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [跨集群复制自动跟随并发触发大小配置](https://easysearch.cn/knowledge-base/easysearch_config/plugins.replication.autofollow.concurrent_replication_jobs_trigger_size/): 配置项作用 # plugins.replication.autofollow.concurrent_replication_jobs_trigger_size 配置项用于控制自动跟随功能触发并发复制任务的阈值大小。 配置项属性 # 配置路径: plugins.replication.autofollow.concurrent_replication_jobs_trigger_size 数据类 … - [跨集群复制自动跟随重试轮询间隔配置](https://easysearch.cn/knowledge-base/easysearch_config/replication.autofollow.retry_poll_interval/): 配置项作用 # replication.autofollow.retry_poll_interval 配置项用于控制自动跟随功能在轮询操作失败后重试的间隔时间。 配置项属性 # 配置路径: replication.autofollow.retry_poll_interval 数据类型: TimeValue（时间值） 默认值: 1m（1分钟） 是否可选: 是 作用域: NodeScope（节点 … - [运行机器学习原生代码失败 - 这可能是由于运行在不支持的系统上导致 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failure-running-machine-learning-native-code-this-could-be-due-to-running-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # 运行机器学习原生代码失败 - 这可能是由于运行在不支持的系统上导致 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 … - [通用脚本异常 (general_script_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/general_script_exception/): 为什么这个错误发生 # general_script_exception 是一个通用的脚本执行异常。当在脚本（如 Painless 脚本）执行过程中发生错误时抛出。 注意：这个异常类已被标记为 @Deprecated，推荐使用更具体的 ScriptException 或其他适当的异常类型。 这个错误可能由以下原因引起： 脚本语法错误：Painless 脚本语法不正确 变量未定义：脚本中引用了未 … - [cleanup snapshot step request for repository [repositoryName] and snapshot [snapshotName] failed to be acknowledged - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cleanup-snapshot-step-request-for-repository-repositoryname-and-snapshot-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.8-7.15 1. 错误异常的基本描述 # 这个异常通常出现在 ILM 或与生命周期相关的快照清理流程中。代码已经表明：请求发送后收到了 AcknowledgedResponse，但 isAcknowledged() 为 false，因此 Elasticsearch 认为这次清理快照步骤没有被集群成功确认。 常见现象 # ILM 策略推进到快照清理步骤时失败。 错误信息中会 … - [Dense ords 不知道如何从多个桶中收集数据 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/dense-ords-don-t-know-how-to-collect-from-many-buckets-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.9-8.9 1. 错误异常的基本描述 # Dense ords 不知道如何从多个桶中收集数据 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返 … - [HipChat Action 与账户 profile 不兼容 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/invalid-hipchataction-type-action-for-watchid-actionid-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-6.8 1. 错误异常的基本描述 # invalid [hipchat] action for [watchId/actionId] action 是 Elasticsearch Watcher 中 HipChat action 的一个配置校验异常。该错误并非消息体 JSON 语法问题，而是 action 模板中使用了当前绑定的 HipChat 账户 profile 所不支 … - [Max shingle size 必须至少为 MAX SHINGLE SIZE LOWER BOUND 且至多 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/max-shingle-size-must-be-at-least-max-shingle-size-lower-bound-and-at-most-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # Max shingle size 必须至少为 MAX SHINGLE SIZE LOWER BOUND 且至多 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请 … - [Na查询格式错误：start_object后没有字段——如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/na-query-malformed-no-field-after-start-object-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Na查询格式错误：start_object后没有字段— 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可 … - [不支持的脚本值：期望一个数字、日期或布尔值 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unsupported-script-value-o-expected-a-number-date-or-boolean-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 不支持的脚本值：期望一个数字、日期或布尔值 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [传输层收到 HTTP 请求 (http_request_on_transport_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/http_request_on_transport_exception/): 为什么这个错误发生 # http_request_on_transport_exception 表示通过传输层（9300 端口）收到了应该发送到 HTTP 层（9200 端口）的请求。 如何修复 # 1. 使用正确的端口 # # 使用 HTTP 端口 9200 而不是传输端口 9300 curl http://localhost:9200/_cluster/health # … - [传输追踪配置](https://easysearch.cn/knowledge-base/easysearch_config/transport.tracer/): 配置项概述 # 传输追踪配置控制哪些传输层操作被记录到追踪日志中。通过配置包含和排除模式，可以精确控制需要追踪的网络操作。 配置项 默认值 说明 transport.tracer.include [] 包含的操作模式列表 transport.tracer.exclude [内部操作] 排除的操作模式列表 配置说明 # transport.tracer.include … - [分片必须具有有效的事务日志UUID但为null - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/shard-must-have-a-valid-translog-uuid-but-got-null-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 分片必须具有有效的事务日志UUID但为null 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返 … - [删除文档](https://easysearch.cn/knowledge-base/easysearch_api/delete-document/): 从索引中删除指定 ID 的文档。 API # DELETE /{index}/_doc/{id} DELETE /{index}/{type}/_doc/{id} API 的作用 # 该 API 用于从索引中删除指定 ID 的文档。 API 变体 # API 描述 DELETE /{index}/_doc/{id} 删除文档（推荐，无类型） DELETE … - [副本分片重试异常 (retry_on_replica_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/retry_on_replica_exception/): 为什么这个错误发生 # retry_on_replica_exception 表示在副本分片上执行的操作失败，需要在副本分片上重试。这通常发生在副本分片状态发生变化或同步过程中。 这个错误可能由以下原因引起： 副本同步中：副本正在从主分片同步数据，暂时无法处理请求 副本迁移中：副本正在迁移到其他节点 副本未初始化：副本尚未完全初始化 网络延迟：主分片到副本的网络延迟导致同步超时 副本故障：副本 … - [同名快照已存在 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/snapshot-with-the-same-name-already-exists-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.4 1. 错误异常的基本描述 # snapshot with the same name already exists 表示 Elasticsearch 在真正写快照前，发现仓库的 RepositoryData 中已经存在同名历史快照，因此直接拒绝本次创建。根据源码，这个检查发生在写全局元数据之前，触发的是 InvalidSnapshotNameException。 它 … - [启动数据馈送 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/starting-datafeed-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # 启动数据馈送 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返回 400、404、409、429、500 … - [延迟重路由原因无法提交 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/delayed-reroute-reason-could-not-be-submitted-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.3-8.9 1. 错误异常的基本描述 # 延迟重路由原因无法提交 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [异步搜索等待完成超时上限](https://easysearch.cn/knowledge-base/easysearch_config/async_search.max_wait_for_completion_timeout/): 配置项作用 # async_search.max_wait_for_completion_timeout 配置项限制异步搜索请求中 wait_for_completion_timeout 参数的最大值。该配置项作为安全机制，防止客户端设置过长的等待时间导致资源占用。 配置项类型 # 该配置项为动态配置，可以在运行时通过集群更新 API 进行修改，无需重启节点。 默认值 # 1m（1分钟） 是 … - [操作大小必须至少为4但实际为 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/operation-size-must-be-at-least-4-but-was-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 操作大小必须至少为4但实际为 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无主节点阻塞级别配置](https://easysearch.cn/knowledge-base/easysearch_config/discovery.zen.no_master_block/): 配置项作用 # discovery.zen.no_master_block 配置项用于控制当集群中没有主节点时，对哪些操作进行限制。 此配置确保在没有主节点协调的情况下，防止执行可能导致数据不一致的操作。 配置项属性 # 配置路径: discovery.zen.no_master_block 数据类型: string（枚举值） 默认值: write 可选值: all, write, … - [无效的聚合器排序路径：未知聚合——如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/invalid-aggregator-order-path-this-unknown-aggregation-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-6.8 1. 错误异常的基本描述 # 无效的聚合器排序路径：未知聚合— 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法删除PID文件 – 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-delete-pid-file-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 无法删除PID文件 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法生成指定类型的动态映射 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-generate-dynamic-mappings-of-type-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.8 1. 错误异常的基本描述 # 无法生成指定类型的动态映射 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [未知的舍入 ID - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unknown-rounding-id-id-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 未知的舍入 ID 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [本地节点不属于初始配置——如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/local-node-is-not-part-of-initial-configuration-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # 本地节点不属于初始配置— 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [格式错误的URL – 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/malformed-url-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 格式错误的URL 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [源文件未找到索引ID - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/source-not-found-index-id-how-to-solve-this-elasticsearch-exception/): 适用版本： 8-8.9 1. 错误异常的基本描述 # 源文件未找到索引ID 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [聚合名称基数必须为1但实际为基数 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/aggregation-name-must-have-cardinality-1-but-was-cardinality-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.9-8.9 1. 错误异常的基本描述 # Aggregation [xxx] must have cardinality 1 but was [N] 是 Elasticsearch 在执行聚合（Aggregation）过程中抛出的运行时异常。该错误的核心含义是：某个聚合器被期望只作用于单个桶（bucket），但实际执行时却遇到了多个桶，即聚合的基数（cardinality）不符 … - [聚合字段下应为 START_OBJECT 却收到其他 token - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/expected-xcontentparser-token-start-object-under-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # Expected [START_OBJECT] under [fieldName], but got a [token] in [aggregationName] 是 Elasticsearch 在解析聚合（Aggregation）DSL 时抛出的 ParsingException。该异常表示：解析器期望在指定字段 fieldName … - [节点出站恢复数量配置](https://easysearch.cn/knowledge-base/easysearch_config/cluster.routing.allocation.node_concurrent_outgoing_recoveries/): 配置项作用 # cluster.routing.allocation.node_concurrent_outgoing_recoveries 配置项控制每个节点上允许同时进行的出站分片恢复操作的最大数量。出站恢复是指节点作为源节点，向其他节点发送分片数据的过程。 配置项类型 # 该配置项为动态配置，可以在运行时通过集群设置 API 进行修改。 默认值 # 2（ … - [节点级写入请求数限制配置](https://easysearch.cn/knowledge-base/easysearch_config/cluster.throttle.node.write.max_requests/): 配置项作用 # 设置节点级别每秒允许的最大写入请求数量。 默认值 # 0（不限制） 配置格式 # # 每秒最多 1000 个请求 cluster.throttle.node.write.max_requests: 1000 # 不限制请求数（默认） cluster.throttle.node.write.max_requests: 0 - [解析GET请求失败 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-the-get-result-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # 解析GET请求失败 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [解析数据帧分析配置ID失败 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-data-frame-analytics-configuration-id-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.9-8.9 1. 错误异常的基本描述 # 解析数据帧分析配置ID失败 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [请求未通过身份验证 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/request-is-not-authenticated-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.9-8.9 1. 错误异常的基本描述 # 请求未通过身份验证 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [读取 indices options 时出现未预期的对象字段 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-read-indices-options-unexpected-object-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.x-8.x 1. 问题含义 # could not read indices options. unexpected object field [field] 表示 Elasticsearch 在读取 indices_options 时，发现某个字段的值是对象结构，但当前解析器只接受布尔值、字符串或特定简化结构，不接受嵌套对象。 … - [预热线程池配置](https://easysearch.cn/knowledge-base/easysearch_config/thread_pool.warmer/): 配置项作用 # thread_pool.warmer 相关配置项控制用于执行索引预热（Warmer）操作的线程池。预热操作在索引打开或刷新时执行，加载全局序数、字段数据等结构到内存，以提高后续查询性能。该线程池采用伸缩线程池类型。 配置项类型 # 该配置项为静态配置，需要在启动时设置，修改后需要重启节点才能生效。 默认值 # thread_pool.warmer.core: 1 … - [CORS 允许的 HTTP 方法配置](https://easysearch.cn/knowledge-base/easysearch_config/http.cors.allow-methods/): 配置项作用 # http.cors.allow-methods 配置项用于指定在跨域资源共享（CORS）请求中允许浏览器使用的 HTTP 方法列表。 当浏览器发送跨域请求的预检（OPTIONS）请求时，服务器会在 Access-Control-Allow-Methods 响应头中返回允许的 HTTP 方法。 配置项属性 # 配置路径: http.cors.allow-methods 数据类 … - [failed to parse bucket - 无法解析 bucket 响应](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-bucket-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # failed to parse bucket 表示 Elasticsearch 从输入流中读取 bucket 数据时，无法按预期结构解析出 Bucket 对象，因此抛出 ElasticsearchParseException。源码会通过 Bucket.LENIENT_PARSER.apply(parser, null) … - [Indices options xcontent did not contain - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/indices-options-xcontent-did-not-contain-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.1-8.9 1. 错误异常的基本描述 # Indices options xcontent did not contain 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 … - [LineString 中的点数无效——必须大于等于 2——如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/invalid-number-of-points-in-linestring-found-must-be-2-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # LineString 中的点数无效——必须大于等于 2— 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接 … - [Profile 文档未找到 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/profile-document-not-found-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.5-8.9 1. 错误异常的基本描述 # Profile 文档未找到 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Repository type repositoryMetadata type does not exist - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/repository-type-repositorymetadata-type-does-not-exist-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.14-8.9 1. 错误异常的基本描述 # repository type [xxx] does not exist 表示 Elasticsearch 已经拿到了 repository metadata 中的 type 字符串，但在当前节点的仓库类型注册表里找不到对应实现。也就是说，这不是 JSON 结构解析失败，而是“类型值存在，但系统不认识它”或者“当前节点没有该类型对应的 … - [Start object expected indices – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/start-object-expected-indices-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.9 1. 错误异常的基本描述 # Start object expected indices 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接 … - [System Write 线程池大小配置](https://easysearch.cn/knowledge-base/easysearch_config/thread_pool.system_write.size/): 配置项作用 # thread_pool.system_write.size 配置项用于控制系统写入线程池的线程数量。 配置项属性 # 配置路径: thread_pool.system_write.size 数据类型: Integer（整数） 默认值: (CPU核心数 + 1) / 2，范围 1-5 是否可选: 是 作用域: NodeScope（节点级别） 动态更新: 否（需要重启节点生效） … - [Transport 发布主机配置](https://easysearch.cn/knowledge-base/easysearch_config/transport.publish_host/): 配置项作用 # transport.publish_host 配置项用于控制节点向其他节点和客户端宣告的访问地址。 配置项属性 # 配置路径: transport.publish_host 数据类型: List<String>（字符串列表） 默认值: 继承自 transport.host（空列表），未设置时使用绑定地址 是否可选: 是 作用域: NodeScope（节点级别） 动 … - [Transport 默认类型配置](https://easysearch.cn/knowledge-base/easysearch_config/transport.type.default/): 配置项作用 # transport.type.default 配置项用于定义默认的传输层实现类型。 配置项属性 # 配置路径: transport.type.default 数据_type: String（字符串） 默认值: netty4 是否可选: 是 作用域: NodeScope（节点级别） 动态更新: 否（需要重启节点生效） 配置建议 # 默认配置 # transport: … - [WKT 字符串结束后发现额外文本 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/expected-end-of-wkt-string-but-found-additional-text-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # WKT 字符串结束后发现额外文本 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [不再主导此发布任期 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/no-longer-leading-this-publication-s-term-how-to-solve-this-elasticsearch-exception/): 适用版本： 7-8.9 1. 错误异常的基本描述 # 不再主导此发布任期 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [分片状态元数据缺失——如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/no-shard-state-meta-data-at-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 分片状态元数据缺失— 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [前缀查询——如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/prefix-query-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.3-8.9 1. 错误异常的基本描述 # 前缀查询— 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [字段 n 上的属性值必须是数字或字符串，但得到了 o – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/property-value-on-field-n-must-be-a-number-or-a-string-but-got-o-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.16-8.9 1. 错误异常的基本描述 # 字段 n 上的属性值必须是数字或字符串，但得到了 o 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可 … - [快照恢复异常 (snapshot_restore_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/snapshot_restore_exception/): 为什么这个错误发生 # snapshot_restore_exception 表示从快照恢复数据时发生错误。快照恢复是将快照中的数据恢复到集群的过程。 这个错误可能由以下原因引起： 快照损坏：快照数据损坏或不完整 仓库不可访问：无法访问快照仓库 索引已存在：目标索引已存在且未配置覆盖 磁盘空间不足：目标节点磁盘空间不足 分片分配失败：无法分配恢复的分片 版本不兼容：快照版本与集群版本不兼容 索 … - [搜索上下文出现意外的 null 索引访问控制 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unexpected-null-indices-access-control-for-search-context-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # 搜索上下文出现意外的 null 索引访问控制 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [操作 actionName 失败 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/operation-actionname-failed-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 操作 actionName 失败 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [故障节点 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/faulty-node-how-to-solve-this-elasticsearch-exception/): 适用版本： 7-8.9 1. 错误异常的基本描述 # 故障节点 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返回 400、404、409、429、500 … - [无法关闭正在进行快照的索引 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-close-indices-that-are-being-snapshotted-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # Cannot close indices that are being snapshotted 表示你发起关闭索引请求时，目标索引仍被当前快照任务引用。Elasticsearch 会在真正修改集群状态前检查这些索引是否出现在 SnapshotsService.snapshottingIndices(...) 的结果里；只要命中，就直接 … - [无法删除临时汇总索引 rollupIndex - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unable-to-delete-the-temporary-rollup-index-rollupindex-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.3-8.3 1. 错误异常的基本描述 # 无法删除临时汇总索引 rollupIndex 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法解析指定的URL urlToCheck - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-parse-the-specified-url-urltocheck-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.16-8.9 1. 错误异常的基本描述 # 无法解析指定的URL urlToCheck 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法解析组件模板 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unable-to-parse-component-template-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.9-8 1. 错误异常的基本描述 # 无法解析组件模板 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [期望分析器是字符串类型 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/expecting-the-analyzer-at-to-be-a-string-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-6.8 1. 错误异常的基本描述 # 期望分析器是字符串类型 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [期望开始对象索引 indexName – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/start-object-expected-index-indexname-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.9 1. 错误异常的基本描述 # 期望开始对象索引 indexName 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [未找到快照生命周期策略 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/snapshot-lifecycle-policy-or-policies-not-found-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.4-7.15 1. 错误异常的基本描述 # snapshot lifecycle policy or policies [...] not found 表示你在读取 SLM policy 时，请求里指定了一个或多个 lifecycleIds，但 Elasticsearch 在当前集群元数据中没有找到对应 policy， … - [查询所有快照仓库](https://easysearch.cn/knowledge-base/easysearch_api/get-all-snapshot-repositories/): 此 API 用于获取集群中所有已注册的快照存储仓库信息。 API # GET /_snapshot API 的作用 # 返回集群中所有已注册的快照存储仓库信息。每个仓库包含： 仓库名称：仓库的唯一标识符 仓库类型：文件系统、S3、HDFS 等 仓库配置：存储位置、压缩设置等 此 API 用于： 查看集群中可用的备份仓库 验证仓库配置是否正确 获取仓库的详细信息用于备份和恢复操作 API … - [源分片尚未标记为正在迁移到目标节点 – 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/source-shard-is-not-marked-yet-as-relocating-to-request-targetnode-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 源分片尚未标记为正在迁移到目标节点 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [类型缺失 (type_missing_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/type_missing_exception/): 为什么这个错误发生 # type_missing_exception 表示请求的类型在索引映射中不存在。在 Easysearch 7.x 及以后，不再支持显式的类型（type），每个文档的 “_type” 字段默认为 “_doc”。 如何修复 # 1. 移除类型引用 # # 不要在 API 请求中指定类型 # 使用 POST … - [系统调用过滤配置](https://easysearch.cn/knowledge-base/easysearch_config/bootstrap.system_call_filter/): 配置项作用 # bootstrap.system_call_filter 配置项控制是否启用系统调用过滤（System Call Filter），基于 Linux seccomp（Secure Computing Mode）机制限制进程可以执行的系统调用，从而增强安全性。 配置项类型 # 该配置项为静态配置，需要在启动时设置，修改后需要重启节点才能生效。 默认值 # true（启用） 是否必 … - [索引无法恢复——存在缺失的段——如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/index-is-unrecoverable-there-are-missing-segments-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # 索引无法恢复——存在缺失的段— 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [聚合中出现意外的标记](https://easysearch.cn/knowledge-base/elasticsearch_error/unexpected-token-token-in-aggregationname-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 聚合中出现意外的标记 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [节点重连间隔配置](https://easysearch.cn/knowledge-base/easysearch_config/cluster.nodes.reconnect_interval/): 配置项作用 # cluster.nodes.reconnect_interval 配置项控制集群中节点之间连接断开后重新连接的间隔时间。当检测到节点间连接断开时，系统会按照此间隔定期尝试重新建立连接，确保集群的高可用性。 配置项类型 # 该配置项为静态配置，需要在 easysearch.yml 配置文件中设置，修改后需要重启节点才能生效。 默认值 # 10s（10秒） 是否必需 # 可选配 … - [解析影响器失败——如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parser-influencer-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 解析影响器失败— 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [许可证构建器 UID 的签名格式错误 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/malformed-signature-for-license-builder-uid-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 许可证构建器 UID 的签名格式错误 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [读取值错误 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/error-reading-values-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 读取值错误 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [cron 数组元素不是字符串 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-cron-schedule-expected-a-string-value-in-the-cron-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # could not parse [cron] schedule. expected a string value in the cron array but found [token] 表示 Elasticsearch Watcher 在解析 schedule.cron 配置时，期望 cron 数组中的每个元素都是字符串类型，但实际遇 … - [Debug FORMAT should be specified at most once - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/debug-format-should-be-specified-at-most-once-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误说明 # Debug FORMAT should be specified at most once 是 Elasticsearch SQL 解析阶段抛出的 ParsingException。当在一条 DEBUG 语句中多次声明 FORMAT 子句时，Elasticsearch 的 SQL 解析器会在语法校验阶段直接拒绝该请求，因为输出格式（FORMAT） … - [HTTP TCP 接收缓冲区大小配置](https://easysearch.cn/knowledge-base/easysearch_config/http.tcp.receive_buffer_size/): 配置项作用 # http.tcp.receive_buffer_size 配置项用于控制HTTP 服务器 TCP 连接的接收缓冲区大小。 TCP 接收缓冲区是操作系统内核为每个 TCP 连接分配的内存区域，用于临时存储从网络接收的数据。缓冲区大小直接影响网络吞吐量和数据处理能力。 配置项属性 # 配置路径: http.tcp.receive_buffer_size 数据类型: … - [Watch reporting Error when polling pdf from host port - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/watch-reporting-error-when-polling-pdf-from-host-port-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # Watch reporting Error when polling pdf from host port 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下 … - [不能同时使用 collapse 和 search_after - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-use-collapse-in-conjunction-with-search-after-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.13 1. 错误异常的基本描述 # 当搜索请求同时包含 collapse 和 search_after，会看到类似错误： cannot use `collapse` in conjunction with `search_after` 这种错误一般会在查询上下文构建阶段被直接拒绝。 2. 为什么会发生这个错误 # search_after 用于基于稳定排序值继续翻页， … - [位置增量间隔必须为正值但得到 v - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/position-increment-gap-must-be-positive-got-v-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.11-8.9 1. 错误异常的基本描述 # 位置增量间隔必须为正值但得到 v 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [分片恢复内部操作超时配置](https://easysearch.cn/knowledge-base/easysearch_config/indices.recovery.internal_action_timeout/): 配置项作用 # indices.recovery.internal_action_timeout 配置项控制分片恢复过程中内部操作的超时时间。这是恢复过程中各个阶段的默认超时时间。 配置项类型 # 该配置项为动态配置，可以在运行时通过集群设置 API 进行修改。 默认值 # 15m 是否必需 # 可选配置项（有默认值） 取值范围 # 0 ~ 正无穷 配置格式 # # … - [分片恢复失败 (index_shard_restore_failed_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/index_shard_restore_failed_exception/): 为什么这个错误发生 # index_shard_restore_failed_exception 表示从快照恢复分片时失败。 如何修复 # 1. 检查快照状态 # GET /_snapshot/<repo>/<snap>?verbose 2. 检查磁盘空间 # GET /_cat/allocation?v 3. 重试恢复 # POST … - [删除规则库](https://easysearch.cn/knowledge-base/easysearch_api/delete-ruleset/): 删除指定的规则库（规则仓库），包括从索引中删除元数据以及从所有节点删除物理文件。 API 格式 # DELETE /_match_rules/{repo_id} API 作用 # 该 API 用于删除规则库，执行以下操作： 检查规则库是否被管道（pipeline）依赖 从 .match_rules 系统索引中删除规则库文档 从集群所有节点删除规则库的物理文件 更新节点元数据 API … - [别名不存在 (aliases_not_found_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/aliases_not_found_exception/): 为什么这个错误发生 # aliases_not_found_exception 表示引用的别名不存在。 如何修复 # 1. 列出所有别名 # GET /_cat/aliases?v 2. 创建别名 # POST /_aliases { "actions": [{ "add": { "index": … - [命令后应跟随数组元素 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/commands-should-follow-with-an-array-element-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 命令后应跟随数组元素 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [字段类型不接受多个值 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/field-type-for-does-not-accept-more-than-single-value-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.8-8.9 1. 错误异常的基本描述 # 字段类型不接受多个值 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [字段缺失 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/field-missing-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.x 1. 错误异常的基本描述 # field [{}] missing 属于解析阶段异常。根据保留代码，这里并不是泛指任意 mapping 字段不存在，而是在解析地理点结构时，发现某个必填字段缺失，例如 lat、lon、type 或 coordinates 只传了一半。 常见现象 # 写入 geo_point、解析 GeoJSON 或地理查询参数时立即报 400。 … - [快照初始化期间主节点变更 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/master-changed-during-snapshot-initialization-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.17 1. 错误异常的基本描述 # master changed during snapshot initialization 表示创建快照的主节点在“初始化快照”这个阶段失去了 master 身份。源码里的处理逻辑很明确：一旦 onNoLongerMaster(...) 被触发，当前节点就不再继续本地清理或推进初始化， … - [总断路器实际内存使用配置](https://easysearch.cn/knowledge-base/easysearch_config/indices.breaker.total.use_real_memory/): 配置项作用 # indices.breaker.total.use_real_memory 配置项控制总断路器是否使用实际 JVM 内存使用量进行限制。 默认值 # true 配置类型 # 动态配置 配置格式 # # 默认配置：使用实际内存 indices.breaker.total.use_real_memory: true # … - [文件名缺失或无效 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/missing-or-invalid-file-name-name-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # 文件名缺失或无效 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法为服务账户主体加载角色——不存在该服务账户——如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-load-role-for-service-account-principal-no-such-service-account-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.16-8.9 1. 错误异常的基本描述 # 无法为服务账户主体加载角色——不存在该服务账户— 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法在 search_as_you_type 类型字段上设置 doc_values – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-set-doc-values-on-field-of-type-search_as_you_type-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.1-8.9 1. 错误异常的基本描述 # 无法在 search_as_you_type 类型字段上设置 doc_values 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判 … - [无法在文本变量上使用表达式 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-use-expression-with-text-variable-using-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 无法在文本变量上使用表达式 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法打开套接字通道 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-open-socket-channel-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.2-8.9 1. 错误异常的基本描述 # 无法打开套接字通道 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法解析版本 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/couldn-t-resolve-version-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # 无法解析版本 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法识别聚合中的 key - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-identify-key-in-agg-k-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # Could not identify key in agg [k] 表示 Elasticsearch 在解析或处理聚合（aggregation）结果时，遇到一个无法识别的 key（k），导致无法继续构建或转换聚合输出。该异常通常出现在自定义插件、Pipeline Aggregation、脚本化聚合，或第三方客户端对聚合结果进行二次解析 … - [无法重写主查询 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-rewrite-main-query-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # 无法重写主查询 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法验证响应 - 响应未包含state参数 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-validate-the-response-the-response-did-not-contain-a-state-parameter-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.2-8.9 1. 错误异常的基本描述 # 无法验证响应 - 响应未包含state参数 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [更新数据框转换状态时出错 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/error-while-updating-state-for-data-frame-transform-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.2-7.4 1. 错误异常的基本描述 # 更新数据框转换状态时出错 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [构建错误 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/error-building-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.12-8.9 1. 错误异常的基本描述 # 构建错误 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [模型分配未路由到节点 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/allocation-for-model-with-id-is-not-routed-to-node-how-to-solve-this-elasticsearch-exception/): 适用版本： 8-8.2 1. 错误异常的基本描述 # 模型分配未路由到节点 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [没有名为且类型为数组的参数 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/no-parameter-named-and-type-array-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 没有名为且类型为数组的参数 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [节点离开请求发送配置](https://easysearch.cn/knowledge-base/easysearch_config/discovery.zen.send_leave_request/): 配置项作用 # discovery.zen.send_leave_request 配置项用于控制节点在关闭或离开集群时是否向主节点发送正式的离开请求。 当节点正常关闭时，可以选择通知主节点，使集群能够更快地检测到节点的离开，并触发相应的重新分配操作。 配置项属性 # 配置路径: discovery.zen.send_leave_request 数据类型: Boolean（布尔值） 默认值: … - [范围时区不能应用于非未映射字段 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/range-time-zone-can-not-be-applied-to-non-unmapped-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.6 1. 错误异常的基本描述 # 范围时区不能应用于非未映射字段 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [解析失败数组失败 - 必须提供 reason 或 cause – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-failures-array-at-least-one-of-reason-cause-must-be-present-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 解析失败数组失败 - 必须提供 reason 或 cause 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [跨集群复制自动跟随获取轮询间隔配置](https://easysearch.cn/knowledge-base/easysearch_config/replication.autofollow.fetch_poll_interval/): 配置项作用 # replication.autofollow.fetch_poll_interval 配置项用于控制自动跟随功能轮询远程集群以发现匹配自动跟随模式的新索引的频率。 配置项属性 # 配置路径: replication.autofollow.fetch_poll_interval 数据类型: TimeValue（时间值） 默认值: 30s（30秒） 是否可选: 是 作用域: … - [跨集群复制领导者线程池队列大小配置](https://easysearch.cn/knowledge-base/easysearch_config/replication.leader.thread_pool.queue_size/): 配置项作用 # replication.leader.thread_pool.queue_size 配置项用于控制领导者复制线程池的队列大小。 配置项属性 # 配置路径: replication.leader.thread_pool.queue_size 数据类型: Integer（整数） 默认值: 0（自动计算为 available_processors × 3/2 + 1） 是否可选: … - [遇到多个权重分配——如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/encountered-more-than-one-weight-for-a-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # 遇到多个权重分配— 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Bucket [bucketName] does not exist - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/bucket-bucketname-does-not-exist-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.8 1. 错误异常的基本描述 # 这条异常出现在 GCS 仓库初始化阶段。GoogleCloudStorageBlobStore 在构造时会先调用 doesBucketExist(bucketName)，如果结果为 false，就直接抛出 BlobStoreException("Bucket [bucketName] does not … - [Constant score 需要一个 filter 元素 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/constant-score-requires-a-filter-element-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Constant score 需要一个 filter 元素 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接 … - [epoch formatter is not supported as dynamic date format - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/epoch-formatter-is-not-supported-as-dynamic-date-format-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Epoch [formatter] is not supported as dynamic date format 是 Elasticsearch 在解析索引映射（mapping）时抛出的异常。当你在映射配置中的 dynamic_date_formats 列表中使用了 epoch_millis、epoch_second 等 epoch … - [Explanation so far 附加信息 - 如何理解此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/n-explanation-so-far-n-n-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.x 1. 这条信息是什么 # Explanation so far: 不是独立的根因异常，而是 Elasticsearch 在捕获真正异常后，额外附加的一段诊断文本。源码会把解析过程中积累的解释信息拼接起来，作为一个 suppressed exception 挂到原始异常上。 因此如果你在日志里看到诸如 Explanation so far:、[ ... ] 之类的内 … - [HTTP 响应压缩配置](https://easysearch.cn/knowledge-base/easysearch_config/http.compression/): 配置项作用 # http.compression 配置项控制是否对 HTTP 响应进行压缩，以减少网络带宽使用并提高传输速度。 是否可选 # 是 默认值 # true (启用压缩) 配置项类型 # 静态配置 - 需要重启节点才能生效 配置格式 # # 默认启用（无需配置） http.compression: true # 禁用压缩 http.compression: false … - [OnFollowerCheckRequest current term is – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/onfollowercheckrequest-current-term-is-how-to-solve-this-elasticsearch-exception/): 适用版本： 7-7.15 1. 错误异常的基本描述 # OnFollowerCheckRequest current term is 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见 … - [Rollup 时间窗口配置](https://easysearch.cn/knowledge-base/easysearch_config/rollup.hours_before/): 配置项作用 # rollup.hours_before 配置项用于控制Rollup 查询的时间边界。 此配置决定了系统回溯多少小时的数据应该从原始索引查询，而不是从 Rollup 索引查询。这确保了最近的数据（还未被 Rollup 的数据）从原始索引查询，而较旧的数据从 Rollup 索引查询。 配置项属性 # 配置路径: rollup.hours_before 数据类型: Integer（ … - [S3 存储库未定义存储桶 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/no-bucket-defined-for-s3-repository-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # No bucket defined for S3 repository 表示 Elasticsearch 在创建、加载或初始化 S3 快照仓库时，没有在仓库 settings 中找到 bucket。对于 S3 仓库来说，bucket 是仓库最核心的定位信息，没有它就无法确定快照数据要写到哪里，因此仓库对象在初始化阶段就会失败。 … - [Transport Netty 接收缓冲区预测最大值配置](https://easysearch.cn/knowledge-base/easysearch_config/transport.netty.receive_predictor_max/): 配置项作用 # transport.netty.receive_predictor_max 配置项用于定义Netty 接收缓冲区分配器的最大预测值。 配置项属性 # 配置路径: transport.netty.receive_predictor_max 数据类型: ByteSizeValue（字节大小，支持 bytes、kb、mb、gb 单位） 默认值: … - [watch 的 HTTP input 出现了意外的字符串字段 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-input-for-watch-unexpected-string-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.x 1. 错误异常的基本描述 # could not parse [http] input for watch [id]. unexpected string field [field] 表示 Watcher 在解析 HTTP input 时，读到了一个字符串值字段，但这个字段名在当前上下文里并不合法。 从附录里的源码可以看出，只有少数字符串字段会被接受，例如内容类型相 … - [不支持字段类型的非BKD字段参数 – 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/non-bkd-field-parameters-are-not-supported-for-field-type-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.11-8.9 1. 错误异常的基本描述 # 不支持字段类型的非BKD字段参数 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [仅当 joinVotes 对新配置具有法定人数时才允许重新配置 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/only-allow-reconfiguration-if-joinvotes-have-quorum-for-new-config-how-to-solve-this-elasticsearch-exception/): 适用版本： 7-8.9 1. 错误异常的基本描述 # 仅当 joinVotes 对新配置具有法定人数时才允许重新配置 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接 … - [作业调度器重试次数配置](https://easysearch.cn/knowledge-base/easysearch_config/jobscheduler.retry_count/): 配置项作用 # jobscheduler.retry_count 配置项用于控制作业调度器的 Job Sweeper 在执行搜索请求失败时的重试次数。 当搜索请求遇到临时性故障（如 502 Bad Gateway、504 Gateway Timeout、503 Service Unavailable 等）时，Job Sweeper 会使用指数退避策略进行重试，此配置决定了最大重试次数。 配置项属 … - [发现未知的许可证版本，请将所有节点升级到最新的 Elasticsearch 版本 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unknown-license-version-found-please-upgrade-all-nodes-to-the-latest-elasticsearch-release-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.6-8.9 1. 错误异常的基本描述 # 发现未知的许可证版本，请将所有节点升级到最新的 Elasticsearch 版本 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判 … - [在等待集群状态更改时无法设置当前集群状态 – 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-set-current-cluster-state-while-waiting-for-a-cluster-state-change-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 在等待集群状态更改时无法设置当前集群状态 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [字段名称发现不支持的形状几何类型 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/field-name-found-an-unsupported-shape-geometry-type-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.11-7.11 1. 错误异常的基本描述 # 字段名称发现不支持的形状几何类型 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [文件系统仓库位置配置](https://easysearch.cn/knowledge-base/easysearch_config/repositories.fs.location/): 配置项作用 # repositories.fs.location 配置项用于指定文件系统仓库的存储位置路径。 这是配置文件系统快照仓库的必需参数，指定了快照数据存储的根目录。所有节点都必须能够访问此位置。 配置项属性 # 配置路径: repositories.fs.location 数据类型: String（文件路径字符串） 默认值: 无（必须配置） 是否可选: 否（必需参数） 作用域: … - [无效的快照名称 (invalid_snapshot_name_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/invalid_snapshot_name_exception/): 为什么这个错误发生 # invalid_snapshot_name_exception 表示快照名称不符合要求。 如何修复 # 1. 使用有效名称 # 不能以 _ 开头 不能包含特殊字符 不能包含空格 2. 正确创建快照 # PUT /_snapshot/<repo>/snapshot-2023-06-15 预防措施 # 使用日期命名快照 - [无法为 timestamp 字段创建映射 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unable-to-create-timestamp-field-mapping-for-field-timestampfield-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.7-8.9 1. 错误异常的基本描述 # Unable to create timestamp field mapping for field [timestampField] 表示 Elasticsearch 在构造或序列化 timestamp 字段 mapping 时发生了内部 IOException。该异常通常出现在涉及时间序列（time series）索引、降采 … - [无法写入ZIP文件file – 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-write-zip-file-file-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.6-8.9 1. 错误异常的基本描述 # 无法写入ZIP文件file 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法在只读存储库上克隆分片快照 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-clone-shard-snapshot-on-a-readonly-repository-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.1-8.9 1. 错误异常的基本描述 # cannot clone shard snapshot on a readonly repository 表示 Elasticsearch 试图在某个仓库里执行分片快照克隆，但目标仓库被配置为只读，因此相关写入或元数据更新操作被拒绝。这里的“clone”并不是简单读取已有快照，而是基于现有快照数据生成新的仓库内部引用关系，因此仍然属于会 … - [无法推导类型 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-derive-type-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 无法推导类型 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法解析监视器执行请求，出现未预期的 Token（Could not parse watch execution request. unexpected token）- 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-watch-execution-request-unexpected-token-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.x 1. 错误异常的基本描述 # could not parse watch execution request. unexpected token [...] 表示 Watcher 在读取执行请求时遇到了不应该出现的 JSON token，例如本来预期字段名、对象或字符串，却读到了数组、数字、布尔值或结束标记。 这说明问题通常出在 JSON 结构本身，而不是业务语义。 … - [映射更新不允许操作——如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/mapping-updates-are-not-allowed-operation-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 映射更新不允许操作— 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [构建聚合结果失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-build-aggregation-aggregator-name-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误说明 # Failed to build aggregation [aggregator_name] 表示 Elasticsearch 在执行完聚合计算后、准备将结果写入响应时发生了异常。该错误并非发生在 DSL 解析或查询执行阶段，而是在结果构造阶段（buildTopLevel）抛出的，因此排查思路与普通查询错误有所不同。 常见现象 # … - [查询指定快照仓库](https://easysearch.cn/knowledge-base/easysearch_api/get-specific-snapshot-repository/): 此 API 用于获取集群中指定快照存储仓库的信息。 API # GET /_snapshot/{repository} API 的作用 # 返回指定快照存储仓库的详细配置信息。可以查看： 仓库类型：文件系统、S3、HDFS 等 存储配置：位置、端点、存储桶等 性能设置：带宽限制、压缩设置等 此 API 用于验证特定仓库的配置是否正确。 API 的参数 # 路由参数 # … - [清除角色缓存失败 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/clearing-the-role-cache-failed-please-clear-the-role-cache-manually-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.8 1. 错误异常的基本描述 # 清除角色缓存失败 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [源分片 routingEntry 不是活跃的主分片 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/source-shard-routingentry-is-not-an-active-primary-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 源分片 routingEntry 不是活跃的主分片 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可 … - [空恢复源 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/empty-restore-source-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # empty restore source 表示某个分片已经开始进入 restore 恢复链路，但 restoreSource 为空，导致 Elasticsearch 无法知道应该从哪个快照源恢复该分片，因此抛出 IndexShardRestoreFailedException。 这类错误不在 restore 请求参数校验阶段，而是在分片 … - [等待LDAP可执行对象执行超时 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/timed-out-waiting-for-execution-of-ldap-runnable-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.16-8.9 1. 错误异常的基本描述 # 等待LDAP可执行对象执行超时 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [索引分片恢复异常 (index_shard_restore_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/index_shard_restore_exception/): 为什么这个错误发生 # index_shard_restore_exception 表示在从快照恢复分片时发生错误。快照恢复是将存储的快照数据恢复到索引的过程。 这个错误可能由以下原因引起： 快照文件损坏：快照存储中的文件损坏或不完整 快照不存在：指定的快照不存在或已被删除 仓库不可访问：快照仓库无法访问（网络问题、认证失败等） 磁盘空间不足：目标节点磁盘空间不足以恢复分片 索引冲突：目标索引 … - [解析权限检查失败：所有权限字段均缺失 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-privileges-check-all-privilege-fields-are-missing-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # 解析权限检查失败：所有权限字段均缺失 说明安全相关请求或外部客户端配置缺少必填项，或者包含了该接口明确不支持的字段。 常见现象 # 请求通常在解析阶段直接失败，常见异常类型是 ElasticsearchParseException、MapperParsingException 或 SettingsException。 … - [资源重载中频检查间隔配置](https://easysearch.cn/knowledge-base/easysearch_config/resource.reload.interval.medium/): 配置项作用 # resource.reload.interval.medium 配置项控制中频资源检查的轮询间隔。 默认值 # 如配置名所示 配置类型 # 静态配置 配置格式 # # 默认配置 resource.reload.interval.medium: default - [aborted by user - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/aborted-by-user-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9+ 1. 错误异常的基本描述 # aborted by user 是 Elasticsearch 在执行集群管理操作（如 RemoveCorruptedShardDataCommand）时抛出的异常。当用户通过终端或管理界面手动中止（输入 N 或 no）正在执行的操作时，就会触发此错误。这通常用于确认危险操作（如删除损坏的分片数据）时，用户选择不继续执行。 … - [and must be set for geo fields - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/and-must-be-set-for-geo-fields-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15+ 1. 错误异常的基本描述 # [origin] and [scale] must be set for geo fields 是 Elasticsearch 在解析 geo 字段（geo_point 或 geo_shape）的 Decay Function Builder（衰减函数构建器）时抛出的参数验证错误。当你在某个查询（ … - [could not parse schedule unexpected field - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-schedule-unexpected-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # could not parse [schedule_type] schedule. unexpected field [field] 是 Elasticsearch Watcher 在解析 schedule（调度）配置时抛出的异常。此错误表示调度定义中出现了当前调度解析器不接受的字段名。 常见现象 # 创建或更新 watch … - [could not parse time time hour is not a number - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-time-time-hour-is-not-a-number-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # could not parse time [value]. time hour [h] is not a number 是 Elasticsearch 在解析时间字符串时抛出的异常。此错误表示时间字符串的 hour 片段（冒号前的部分）不能被解析成整数。 该错误通常发生在 hour 片段包含非数字字符时，属于时间字符串的数值解析错误。 … - [ExistsQueryBuilder NAME 必须提供字段参数——如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/existsquerybuilder-name-must-be-provided-with-a-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # ExistsQueryBuilder NAME 必须提供字段参数— 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Has child 查询不支持 currentFieldName – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/has-child-query-does-not-support-currentfieldname-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Has child 查询不支持 currentFieldName 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [QueryName 查询不支持多个字段 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/queryname-query-doesn-t-support-multiple-fields-found-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # QueryName 查询不支持多个字段 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [SAML 认证请求没有签发者 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/saml-authentication-request-has-no-issuer-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.7-8.9 1. 错误异常的基本描述 # SAML 认证请求没有签发者 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Span not exclude 必须是 span query 类型 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/span-not-exclude-must-be-of-type-span-query-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Span not exclude 必须是 span query 类型 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 … - [Span not 必须包含 exclude span query 子句 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/span-not-must-have-exclude-span-query-clause-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Span not 必须包含 exclude span query 子句 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 … - [Terms 聚合中参数 required_size 和 shard_size 必须大于 0 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/parameters-required-size-and-shard-size-must-be-0-in-terms-aggregation-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Terms 聚合中参数 required_size 和 shard_size 必须大于 0 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引 … - [不能在 scroll 上下文中使用 collapse - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-use-collapse-in-a-scroll-context-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 当请求里同时出现 scroll 和 collapse 时，Elasticsearch 会抛出异常： cannot use `collapse` in a scroll context 这种错误通常在搜索请求进入查询阶段前就会被拦截，因此不会靠重试自行恢复。 2. 为什么会发生这个错误 # scroll 的目标是稳定地遍历一批原始命中结 … - [事务日志损坏 (translog_corrupted_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/translog_corrupted_exception/): 为什么这个错误发生 # translog_corrupted_exception 表示事务日志文件已损坏，无法读取或恢复数据。 这个错误可能由以下原因引起： 磁盘故障：物理磁盘损坏 异常断电：突然断电导致写入不完整 文件系统错误：文件系统损坏 内存错误：内存错误导致数据损坏 如何修复这个错误 # 1. 检查磁盘健康 # # 检查磁盘错误 dmesg | grep -i error … - [分片存储获取线程池配置](https://easysearch.cn/knowledge-base/easysearch_config/thread_pool.fetch_shard_store/): 配置项作用 # thread_pool.fetch_shard_store 相关配置项控制用于获取分片存储文件操作的线程池。当需要打开分片并获取其存储文件信息时使用此线程池。该线程池采用伸缩线程池类型。 配置项类型 # 该配置项为静态配置，需要在启动时设置，修改后需要重启节点才能生效。 默认值 # thread_pool.fetch_shard_store.core: 1 … - [创建仓库失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-create-repository-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # failed to create repository 说明 Elasticsearch 在创建快照仓库时就失败了。这个仓库可能是本地文件系统仓库，也可能是 S3、GCS、Azure、HDFS 等远程对象存储。异常往往发生在仓库初始化、配置校验、底层存储连接或权限检查阶段，还没进入真正的快照执行过程。 从当前源码片段看， … - [命令不支持复杂JSON令牌 – 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/command-does-not-support-complex-json-tokens-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 命令不支持复杂JSON令牌 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [字段必须是 lat/lon 或 geohash 格式 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/field-must-be-either-lat-lon-or-geohash-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.1 1. 错误异常的基本描述 # 字段必须是 lat/lon 或 geohash 格式 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能 … - [强制合并线程池配置](https://easysearch.cn/knowledge-base/easysearch_config/thread_pool.force_merge/): 配置项作用 # thread_pool.force_merge 相关配置项控制用于执行强制合并（Force Merge）操作的线程池。强制合并操作用于将索引的多个段合并成更少的段，以优化查询性能和释放磁盘空间。该线程池采用固定大小线程池类型，默认只有 1 个线程。 配置项类型 # 该配置项为静态配置，需要在启动时设置，修改后需要重启节点才能生效。 默认值 # … - [握手失败因为连接重置 – 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/handshake-failed-because-connection-reset-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # 握手失败因为连接重置 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [搜索过期快照失败 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/search-for-expired-snapshots-failed-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.1-8.9 1. 错误异常的基本描述 # Search for expired snapshots failed 出现在 Elasticsearch 机器学习作业的 model snapshot 保留流程中。这里的 snapshot 不是仓库备份快照，而是 ML job 训练过程中保存的模型快照。源码显示，在为某个 job 搜索哪些 model snapshot 已经过期、可以 … - [断路器异常 (circuit_breaking_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/circuit_breaking_exception/): 为什么这个错误发生 # circuit_breaking_exception 表示断路器被触发。断路器是 Easysearch 的内存保护机制，防止操作消耗过多内存导致 OutOfMemoryError。 这个错误可能由以下原因引起： 请求过大：单个请求尝试加载过多数据到内存 聚合数据过多：聚合操作产生的桶数量过多 字段数据缓存：字段数据（fielddata）缓存占用过多内存 请求级断路器：单 … - [无效的月份日期值字符串值无法转换 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/invalid-month-day-value-string-value-cannot-be-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 无效的月份日期值字符串值无法转换 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法为字段添加值——如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-add-a-value-for-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # 无法为字段添加值— 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法启动 Data Frame Analytics 任务，分配说明显示失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-start-data-frame-analytics-task-allocation-explanation-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.3-7.10 1. 错误异常的基本描述 # Could not start data frame analytics task; allocation explanation [...] 表示 Elasticsearch 无法将 Data Frame Analytics 任务分配到可用的机器学习节点上执行，并返回 429 TOO_MANY_REQUESTS 状态码。 … - [无法获取搜索器源 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-acquire-searcher-source-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.9 1. 错误异常的基本描述 # 无法获取搜索器源 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法解析索引的分片路径 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unable-to-resolve-shard-path-for-index-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.6-7.15 1. 错误异常的基本描述 # 无法解析索引的分片路径 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [未指定运行时字段fieldName的类型 – 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/no-type-specified-for-runtime-field-fieldname-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.11-8.9 1. 错误异常的基本描述 # 未指定运行时字段fieldName的类型 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [未知属性 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unknown-property-fieldname-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Unknown property: [fieldName] 表示 Elasticsearch 已经进入某个已知对象的解析分支，但当前字段名不在该分支允许的参数列表里，因此直接拒绝继续解析。 从当前页面保留的源码片段看，这类异常不是网络、权限或执行阶段故障，而是 请求体里的字段名写错、写多了，或者放错了层级。示例片段中它出现在 Graph … - [未知的谓词 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unknown-predicate-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 未知的谓词 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [查询指定数据流](https://easysearch.cn/knowledge-base/easysearch_api/get-specific-data-stream/): 此 API 用于获取 Easysearch 集群中一个或多个指定数据流（Data Stream）的详细信息。 API # GET /_data_stream/{name} API 的作用 # 获取指定数据流的元数据信息，包括： 数据流名称：数据流的唯一标识符 时间戳字段配置：数据流使用的时间戳字段名称 底层索引列表：构成数据流的所有后备索引 生成号：数据流的当前生成版本号 健康状态：数据流的 … - [节点角色配置](https://easysearch.cn/knowledge-base/easysearch_config/node.roles/): 配置项作用 # node.roles 配置项指定节点的角色，决定节点在集群中的功能。每个角色对应不同的职责，合理分配角色可以优化集群性能和资源使用。 配置项类型 # 该配置项为静态配置，需要在启动时设置，修改后需要重启节点才能生效。 默认值 # [master, data, ingest, remote_cluster_client] 是否必需 # 可选配置项（有默认值） 可用角色 # … - [获取关闭读锁失败 – 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-acquire-close-read-lock-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # 获取关闭读锁失败 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [跨集群复制跟随者启动阻塞配置](https://easysearch.cn/knowledge-base/easysearch_config/plugins.replication.follower.block.start/): 配置项作用 # plugins.replication.follower.block.start 配置项用于控制跟随者索引在与领导者同步前是否阻塞启动。 配置项属性 # 配置路径: plugins.replication.follower.block.start 数据类型: Boolean（布尔值） 默认值: false 是否可选: 是 作用域: NodeScope（节点级别） 动态更新: … - [集群名称配置](https://easysearch.cn/knowledge-base/easysearch_config/cluster.name/): 配置项作用 # cluster.name 配置项定义 Easysearch 集群的唯一名称。只有集群名称相同的节点才能组成同一个集群。 配置项类型 # 该配置项为静态配置，需要在启动时设置，修改后需要重启节点才能生效。 默认值 # easysearch 是否必需 # 可选配置项（但强烈建议为每个集群设置明确的名称） 命名规则 # 不能为空 不能包含冒号（:） 建议使用有意义的名称 工 … - [集群状态慢写入日志阈值配置](https://easysearch.cn/knowledge-base/easysearch_config/gateway.slow_write_logging_threshold/): 配置项作用 # gateway.slow_write_logging_threshold 配置项用于设置集群状态写入操作的慢日志记录阈值。 当集群状态写入操作的时间超过此阈值时，会记录 WARN 级别的日志；低于此阈值时，记录 DEBUG 级别的日志。 配置项属性 # 配置路径: gateway.slow_write_logging_threshold 数据类型: TimeValue（时间 … - [bool query does not support [currentFieldName] – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/bool-query-does-not-support-currentfieldname-how-to-solve-this-elasticsearch-exception/): 适用版本： 5.x、6.x、7.x、8.x（全版本通用） 1. 错误异常的基本描述 # bool query does not support [currentFieldName] 是 Elasticsearch 在解析 DSL 查询时抛出的 ParsingException。该错误表示：在 bool 查询的 JSON 结构中，出现了一个 Elasticsearch 无法识别的字段 … - [cannot snapshot while relocating - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-snapshot-while-relocating-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 快照不是对任意分片副本随便抓一份数据，而是要求在稳定的主分片视图上执行。源码明确规定：如果主分片当前正处于 relocation 过程中，就直接抛出 cannot snapshot while relocating，避免拿到不一致的分片状态。 常见现象 # 手动执行快照时，只有部分分片失败。 集群同时在做 rebalance、节点下 … - [DFS 搜索阶段执行失败 (dfs_phase_execution_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/dfs_phase_execution_exception/): 为什么这个错误发生 # dfs_phase_execution_exception 是在搜索查询的 DFS（Document Frequency Search，文档频率搜索）阶段执行失败时抛出的错误。 DFS 阶段是 Easysearch 搜索过程中的一个重要阶段，用于在执行实际查询之前从每个分片收集额外的统计信息（如文档频率、字段统计等），以便在分布式搜索中更准确地计算评分，确保来自不同分片的 … - [HTTP UI 界面启用配置](https://easysearch.cn/knowledge-base/easysearch_config/http.ui.enabled/): 配置项作用 # http.ui.enabled 配置项控制是否启用 Easysearch 的 Web UI 管理界面访问。当启用时，可以通过 HTTP 访问静态 Web 文件。 是否可选 # 是 默认值 # true (启用 Web UI) 配置项类型 # 静态配置 - 需要重启节点才能生效 配置格式 # # 启用 Web UI（默认） http.ui.enabled: true # 禁 … - [Ingest Grok 看门狗最大执行时间配置](https://easysearch.cn/knowledge-base/easysearch_config/ingest.grok.watchdog.max_execution_time/): 配置项作用 # ingest.grok.watchdog.max_execution_time 配置项控制 Grok 模式匹配器的最大执行时间限制。 默认值 # 1s 配置类型 # 静态配置 配置格式 # # 默认配置 ingest.grok.watchdog.max_execution_time: 1s # … - [Invalid date received - 收到无效日期输入如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/invalid-date-received-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # Invalid date received; ... 表示 Elasticsearch 在将输入文本转换为日期字面量时失败，常见于 Elasticsearch SQL 或 EQL 查询解析路径中。当 SQL 语句或表达式中的日期字符串无法被解析为有效的 java.time.LocalDate 对象时， … - [Mapper 上的 PropName – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/propname-on-mapper-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.9-7.15 1. 错误异常的基本描述 # Mapper 上的 PropName 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [SendFileStep 失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/sendfilestep-failed-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.3-8.9 1. 错误异常的基本描述 # SendFileStep 失败 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Transport TCP Keep-Alive 探测间隔配置](https://easysearch.cn/knowledge-base/easysearch_config/transport.tcp.keep_interval/): 配置项作用 # transport.tcp.keep_interval 配置项用于控制TCP keep-alive 探测之间的间隔时间（秒）。 配置项属性 # 配置路径: transport.tcp.keep_interval 数据类型: Integer（整数，秒） 默认值: -1（使用操作系统默认值） 是否可选: 是 作用域: NodeScope（节点级别） 动态更新: 否（需要重启节点生 … - [Transport 慢操作日志阈值配置](https://easysearch.cn/knowledge-base/easysearch_config/transport.slow_operation_logging_threshold/): 配置项作用 # transport.slow_operation_logging_threshold 配置项用于定义传输层操作触发慢操作警告日志的时间阈值。 配置项属性 # 配置路径: transport.slow_operation_logging_threshold 数据类型: TimeValue（时间值） 默认值: 5s（5秒） 是否可选: 是 作用域: NodeScope（节点级别） … - [TrustManager 初始化失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-initialize-trustmanager-for-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # TrustManager 初始化失败 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Unsupported symbol in point - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unsupported-symbol-in-point-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.6-8.9 1. 错误异常的基本描述 # Unsupported symbol in point 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可 … - [不支持的形状类型 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unsupported-shape-type-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.1-8.9 1. 错误异常的基本描述 # 不支持的形状类型 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [包装 Searcher 失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-wrap-searcher-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误说明 # failed to wrap searcher 表示 Elasticsearch 在将底层 Engine.Searcher 包装为可供查询使用的新 searcher 时发生了 IOException。该异常通常出现在搜索请求准备阶段，意味着索引读取链路中的某个环节出现了问题，导致搜索器无法正常初始化。 常见现象 # 搜索请求随机或持续失败，返 … - [多匹配查询未指定文本 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/no-text-specified-for-multi-match-query-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 多匹配查询未指定文本 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [字段使用未知相似度类型](https://easysearch.cn/knowledge-base/elasticsearch_error/unknown-similarity-type-value-for-field-name-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 字段使用未知相似度类型 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [引擎创建失败异常 (engine_creation_failure_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/engine_creation_failure_exception/): 为什么这个错误发生 # engine_creation_failure_exception 表示在创建分片的搜索引擎（Engine）时失败。Engine 是 Easysearch 中用于处理文档索引、更新、删除和搜索的核心组件，每个分片都有自己的 Engine 实例。 这个错误可能由以下原因引起： 索引文件损坏：Lucene 索引文件损坏或丢失 事务日志（Translog）损坏：事务日志文件损 … - [形状编码失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-encode-shape-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.8-8.9 1. 错误异常的基本描述 # 形状编码失败 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [数据流无法创建，因为支持索引已存在 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/data-stream-could-not-be-created-because-backing-index-already-exists-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.9-8.11 1. 错误异常的基本描述 # 数据流无法创建，因为支持索引已存在 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [文件系统仓库块大小配置](https://easysearch.cn/knowledge-base/easysearch_config/repositories.fs.chunk_size/): 配置项作用 # repositories.fs.chunk_size 配置项用于控制文件系统仓库中快照文件的分块大小。 当使用文件系统（fs）仓库进行快照时，大文件可以被分割成多个块（chunks）存储。此配置决定了每个块的大小，影响快照和恢复的性能以及容错性。 配置项属性 # 配置路径: repositories.fs.chunk_size 数据类型: ByteSizeValue（字节大小 … - [文本相似度结果没有数据——如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/text-similarity-result-has-no-data-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.5-8.9 1. 错误异常的基本描述 # 文本相似度结果没有数据— 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法索引到汇总索引 rollupIndexName - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unable-to-index-into-rollup-index-rollupindexname-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.3-8.9 1. 错误异常的基本描述 # 无法索引到汇总索引 rollupIndexName 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [更新集群状态时发生未知错误 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unknown-error-occurred-while-updating-cluster-state-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 更新集群状态时发生未知错误 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [最小索引缓冲区大小配置](https://easysearch.cn/knowledge-base/easysearch_config/indices.memory.min_index_buffer_size/): 配置项作用 # indices.memory.min_index_buffer_size 配置项控制每个分片的最小索引缓冲区大小。当根据总分片数平均分配的缓冲区小于此值时，每个分片将使用此最小值，而不是平均值。 配置项类型 # 该配置项为静态配置，需要在启动时设置，修改后需要重启节点才能生效。 默认值 # 48mb 是否必需 # 可选配置项（有默认值） 取值范围 # 0 ~ 正无穷 配置 … - [期望坐标数组时发现单个坐标——如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/single-coordinate-found-when-expecting-an-array-of-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # 期望坐标数组时发现单个坐标— 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [清理 S3 仓库时必须指定 Bucket 选项 —— 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/bucket-option-is-required-for-cleaning-up-s3-repository-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.4-7.5 1. 错误异常的基本描述 # bucket option is required for cleaning up S3 repository 表示 Elasticsearch 正在尝试对 S3 快照仓库执行 cleanup，但当前参数里没有提供 bucket。对于 S3 仓库而言，bucket 是最基础的存储容器标识，没有它就无法确定应该扫描和清理哪个对象集合， … - [清理快照仓库](https://easysearch.cn/knowledge-base/easysearch_api/cleanup-snapshot-repository/): 从快照仓库中删除过期的数据，释放存储空间。 API 格式 # POST /_snapshot/{repository}/_cleanup API 作用 # 该 API 用于清理快照仓库中的孤立数据： 删除不再被仓库元数据引用的快照 blob 文件 清理过期的索引生成文件 删除孤儿索引的 blob 容器 移除不再需要的旧分片生成文件 API 参数 # 路径参数 # 参数 类型 是否 … - [缺失或无效的 written_by 字段 writtenByStr - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/missing-or-invalid-written-by-writtenbystr-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # 缺失或无效的 written_by 字段 writtenByStr 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现 … - [解析或加载 source 失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-load-source-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.x 1. 错误异常的基本描述 # failed to parse / load source 通常出现在某段逻辑需要把已有 source 字节重新装载为可解析内容时。源码里无论是直接使用 BytesSourceProvider，还是从现有 bytes 恢复 _source，只要 parseSource() 失败，就会抛出这个异常。 常见现象 # 更新、重建、脚本处理 … - [解析数据馈送配置失败 datafeedId - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-datafeed-config-datafeedid-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 解析数据馈送配置失败 datafeedId 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [评估错误 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/error-evaluating-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 评估错误 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返回 400、404、409、429、500 … - [atomicarrays can only be copied to arrays of the same size - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/atomicarrays-can-only-be-copied-to-arrays-of-the-same-size-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # atomicarrays can only be copied to arrays of the same size 是 Elasticsearch 在执行阶段触发的一个内部异常，核心含义是：在执行过程中，系统试图将一个 AtomicArray 复制到另一个大小不同的 AtomicArray 中，导致数组维度不一致而失败。 该异常通常出 … - [azure proxy type has been set but proxy host or port is not defined - Azure 代理类型已设置但缺少主机或端口如何解决](https://easysearch.cn/knowledge-base/elasticsearch_error/azure-proxy-type-has-been-set-but-proxy-host-or-port-is-not-defined-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Azure Proxy type has been set but proxy host or port is not defined 表示在配置 Elasticsearch 的 Azure 快照仓库（Snapshot Repository）时，代理配置不完整：设置了 proxy.type，但没有设置 proxy.host … - [Get 线程池大小配置](https://easysearch.cn/knowledge-base/easysearch_config/thread_pool.get.size/): 配置项作用 # thread_pool.get.size 配置项用于控制文档获取线程池的固定线程数量。 Get 线程池专门用于处理文档获取操作（get 请求），是查询性能的关键组件。 配置项属性 # 配置路径: thread_pool.get.size 数据类型: Integer（整数） 默认值: CPU核心数（allocatedProcessors） 是否可选: 是 作用域: … - [HTTP TCP Keep-Alive 探测次数配置](https://easysearch.cn/knowledge-base/easysearch_config/http.tcp.keep_count/): 配置项作用 # http.tcp.keep_count 配置项用于控制在判定连接断开之前，TCP Keep-Alive 机制发送探测包的重试次数。 当连接空闲且未收到对 Keep-Alive 探测的响应时，系统会持续发送探测包。此配置指定了在放弃连接并判定为断开之前，最多发送多少个探测包。 配置项属性 # 配置路径: http.tcp.keep_count 数据类型: Integer（整数） … - [HTTP 服务端口配置](https://easysearch.cn/knowledge-base/easysearch_config/http.port/): 配置项作用 # http.port 配置项指定 Easysearch HTTP REST API 服务监听的端口范围。客户端通过此端口执行索引、搜索、集群管理等操作。 配置项类型 # 该配置项为静态配置，需要在启动时设置，修改后需要重启节点才能生效。 默认值 # 9200-9300 是否必需 # 可选配置项（有默认值） 配置格式 # # 单个端口 http.port: 9200 # 端口 … - [HTTP 读取超时配置](https://easysearch.cn/knowledge-base/easysearch_config/http.read_timeout/): 配置项作用 # http.read_timeout 配置项指定 HTTP 服务器等待客户端发送数据的最大时间，防止连接长时间占用资源。 是否可选 # 是 默认值 # 0 (无超时限制) 配置项类型 # 静态配置 - 需要重启节点才能生效 配置格式 # # 无超时限制（默认） http.read_timeout: 0 # 设置 30 秒超时 http.read_timeout: 30s # … - [safety_gap_millis 应为非负数 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/safety-gap-millis-should-be-non-negative-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.4-7.17 1. 错误异常的基本描述 # safety_gap_millis 应为非负数 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [SAML消息无法解压 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/saml-message-cannot-be-inflated-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.7-8.9 1. 错误异常的基本描述 # SAML消息无法解压 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Term查询不支持数组值——如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/term-query-does-not-support-array-of-values-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Term查询不支持数组值— 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [watch action 缺少 action type - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-watch-action-missing-action-type-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # could not parse watch action [watchId/actionId]. missing action type 是 Elasticsearch Watcher（告警监视器）在解析 watch 定义时抛出的异常。该错误表示 Elasticsearch 在解析某个 watch 的 action 配置时，无法识别出具 … - [watch 的 search input 中 request 片段解析失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-input-for-watch-failed-to-parse-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.x 1. 错误异常的基本描述 # could not parse [search] input for watch [id]. failed to parse [request] 表示 Watcher 已经确认这是一个 search input，并开始解析 request 字段， … - [不支持 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/does-not-support-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.16-8.9 1. 错误异常的基本描述 # 不支持 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返回 400、404、409、429、500 … - [分片恢复长操作超时配置](https://easysearch.cn/knowledge-base/easysearch_config/indices.recovery.internal_action_long_timeout/): 配置项作用 # indices.recovery.internal_action_long_timeout 配置项控制分片恢复过程中耗时较长的内部操作的超时时间。此超时时间大于 standard internal_action_timeout，用于需要更长时间完成的恢复阶段。 配置项类型 # 该配置项为动态配置，可以在运行时通过集群设置 API 进行修改。 默认值 # 30m 是否必需 # … - [分片状态重路由优先级配置](https://easysearch.cn/knowledge-base/easysearch_config/cluster.routing.allocation.shard_state.reroute.priority/): 配置项作用 # cluster.routing.allocation.shard_state.reroute.priority 配置项控制分片状态变化（如分片启动、失败）后，后续重路由（reroute）任务的优先级。此配置用于调整集群在处理分片状态变化后重新分配分片的紧急程度。 注意：此配置已标记为已弃用，是专家级的最后手段配置项，不推荐普通用户修改。 配置项类型 # 该配置项为动态配置， … - [分配已存在 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/allocation-already-exists-how-to-solve-this-elasticsearch-exception/): 适用版本： 8-8.2 1. 错误异常的基本描述 # 分配已存在 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [别名过滤器解析异常 (alias_filter_parsing_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/alias_filter_parsing_exception/): 为什么这个错误发生 # alias_filter_parsing_exception 表示在解析索引别名的过滤器时发生错误。索引别名可以关联过滤器，用于限制通过该别名可见的文档范围。 这个错误可能由以下原因引起： 过滤器语法错误：过滤器的查询语法不正确 字段不存在：过滤器引用的字段在索引映射中不存在 数据类型不匹配：过滤器使用的操作与字段数据类型不兼容 过期的查询格式：使用了已弃用或不再支持的 … - [合并/减少聚合计算失败 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/merging-reducing-the-aggregations-failed-when-computing-the-aggregation-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # 合并/减少聚合计算失败 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [字段名 typeName 类型不支持 exists 查询 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/field-name-of-type-typename-does-not-support-exists-queries-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.11-8.9 1. 错误异常的基本描述 # 字段名 typeName 类型不支持 exists 查询 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接 … - [接收超时 (receive_timeout_transport_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/receive_timeout_transport_exception/): 为什么这个错误发生 # receive_timeout_transport_exception 表示节点间通信接收超时。 如何修复 # 1. 检查网络状态 # ping <node> telnet <node> 9300 2. 增加超时时间 # transport.ping_timeout: 30s 3. 检查节点负载 # GET /_nodes/stats 预防 … - [无法创建 XContent 附件（could not create an xcontent attachment [...]）- 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-create-an-xcontent-attachment-name-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.x 1. 错误异常的基本描述 # could not create an xcontent attachment [...] 表示 Elasticsearch 在将某个附件对象序列化为 XContent 字节流时失败。该错误最常见于 Watcher 执行阶段，当 Watcher 尝试把附件（attachment）内容写入通知动作（如 email action 的附 … - [无法删除转换 – 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-delete-transform-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.5-7.5 1. 错误异常的基本描述 # 无法删除转换 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返回 400、404、409、429、500 … - [无法更新存储库中的快照 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-update-snapshot-in-repository-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # failed to update snapshot in repository 表示 Elasticsearch 在 snapshot 的最终提交阶段，无法把新的快照状态、分片 generation 或 index generation 等元数据更新回仓库。结合当前源码片段，这一步通常发生在 finalizeSnapshot 附近，也就 … - [无法解析动态附件，缺少必需字段（Could not parse dynamic attachments. missing required field）- 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-dynamic-attachments-missing-required-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.x 1. 错误异常的基本描述 # could not parse dynamic attachments. missing required field [...] 是 Elasticsearch Watcher 在解析动态附件（dynamic attachments）配置时抛出的解析异常。该错误表示 Watcher 已经成功识别了 dynamic … - [无法解析词向量请求，字段 fields 必须是数组 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-term-vectors-request-field-fields-must-be-an-array-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误说明 # 在使用 Elasticsearch 的 _termvectors 接口时，如果请求体中 fields 字段的格式不符合要求，就会触发如下异常： failed to parse term vectors request. field [fields] must be an array 这是一个解析阶段的异常，Elasticsearch 在反序列化请 … - [服务账户不支持创建 OAuth2 令牌 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/oauth2-token-creation-is-not-supported-for-service-accounts-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.14-8.9 1. 错误异常的基本描述 # 服务账户不支持创建 OAuth2 令牌 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [期望对象但发现了标记 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/expected-an-object-but-found-token-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # expected an object but found token 是 Elasticsearch 在解析 JSON 请求体时抛出的常见异常，表示解析器在当前位置期望看到一个 JSON 对象（即 { 开头），但实际遇到的却是其他类型的标记（如字符串、数组、数值或 null）。这类错误通常发生在请求体构造不正确、 … - [期望平衡尚未计算 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/desired-balance-is-not-computed-yet-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.6-8.9 1. 错误异常的基本描述 # 期望平衡尚未计算 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [构建空聚合时发生IO错误 – 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/io-error-while-building-empty-agg-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.13-8.9 1. 错误异常的基本描述 # 构建空聚合时发生IO错误 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [查询恢复状态](https://easysearch.cn/knowledge-base/easysearch_api/get-recovery-status/): 此 API 用于显示集群中分片恢复的状态信息和进度。 API # GET /_cat/recovery GET /_cat/recovery/{index} API 的作用 # 返回集群中分片恢复的详细信息，包括： 恢复进度：文件和字节的恢复百分比 恢复速度：已恢复的文件数和字节数 恢复类型：节点间复制或从快照恢复 源和目标节点：恢复的源节点和目标节点信息 时间信息：恢复的开始时间、结束时间 … - [检查 blob 是否存在失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-check-if-blob-blobname-exists-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 这条 Failed to check if blob [blobName] exists 来自单对象存在性探测逻辑。源码中调用底层客户端的 doesObjectExist(bucket, buildKey(blobName))；只要这个 head/existence check 抛出异常， … - [遇到多个排序值 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/encountered-more-than-one-sort-value-for-a-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.11-7.15 1. 错误异常的基本描述 # 遇到多个排序值 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [配置中的文件不存在 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/file-from-setting-does-not-exist-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.7-7.15 1. 错误异常的基本描述 # 配置中的文件不存在 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [重置模式已启用 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/reset-mode-has-been-enabled-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.13-8.9 1. 错误异常的基本描述 # 重置模式已启用 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [failed to load kuromoji user dictionary - Kuromoji 用户词典加载失败](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-load-kuromoji-user-dictionary-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # failed to load kuromoji user dictionary 出现在 Kuromoji 分词器（用于日文文本分析）初始化用户词典时。源码会把规则行拼接成字符串，再通过 UserDictionary.open(new StringReader(...)) 读取；若这里抛出 IOException，就会包装成当前异常。 这 … - [Flush 线程池最大大小配置](https://easysearch.cn/knowledge-base/easysearch_config/thread_pool.flush.max/): 配置项作用 # thread_pool.flush.max 配置项用于控制索引刷新线程池的最大线程数。 这是线程池能够创建的最大线程数量上限。 配置项属性 # 配置路径: thread_pool.flush.max 数据类型: Integer（整数） 默认值: (CPU核心数 + 1) / 2，最大不超过 5 是否可选: 是 作用域: NodeScope（节点级别） 动态更新: 是（可以动态 … - [ISM 历史索引最大文档数配置](https://easysearch.cn/knowledge-base/easysearch_config/index_state_management.history.max_docs/): 配置项作用 # index_state_management.history.max_docs 配置项用于控制ISM 历史索引触发滚动操作前的最大文档数量。 当历史索引的文档数达到此配置值时，系统会自动创建新的历史索引并将写入别名指向新索引。 配置项属性 # 配置路径: index_state_management.history.max_docs 数据类型: Long（整数） 默认值: … - [Java签名算法不可用于SAML XML-Sig算法——如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/java-signature-algorithm-is-not-available-for-saml-xml-sig-algorithm-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.7-7.15 1. 错误异常的基本描述 # Java签名算法不可用于SAML XML-Sig算法— 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能 … - [Meta字段条目超过5个限制 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/meta-can-t-have-more-than-5-entries-but-got-meta-size-on-field-name-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.16-8.9 1. 错误异常的基本描述 # Meta字段条目超过5个限制 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Pipe expects a positive integer but found – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/pipe-expects-a-positive-integer-but-found-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.9-7.15 1. 错误异常的基本描述 # Pipe expects a positive integer but found 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判 … - [Profile 索引不存在 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/profile-index-does-not-exist-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.5-8.9 1. 错误异常的基本描述 # Profile 索引不存在 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Top hits 聚合不能与时间序列聚合一起使用 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/top-hits-aggregations-cannot-be-used-together-with-time-series-aggregations-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.1-8.9 1. 错误异常的基本描述 # Top hits 聚合不能与时间序列聚合一起使用 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Unexpected token [token] - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unexpected-token-token-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # unexpected token [token] 是 Elasticsearch 在解析查询 DSL（Domain Specific Language）时抛出的 ParsingException 异常。当查询 JSON 的结构不符合 Elasticsearch 查询解析器的预期时，解析器会在当前解析位置遇到一个"意 … - [不允许使用HTTP URI uriString 仅支持HTTPS - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/not-allowed-to-use-http-uri-uristring-only-https-is-supported-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.2-8.9 1. 错误异常的基本描述 # 不允许使用HTTP URI uriString 仅支持HTTPS 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [为 Rollup Job ID 创建任务失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/creation-of-task-for-rollup-job-id-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # 为 Rollup Job ID 创建任务失败 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返 … - [主分片未激活 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/primary-shard-is-not-active-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.9-8.9 1. 错误异常的基本描述 # 主分片未激活 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返回 400、404、409、429、500 … - [任务不支持取消 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/task-doesn-t-support-cancellation-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.7 1. 错误异常的基本描述 # 任务不支持取消 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返回 400、404、409、429、500 … - [准备分片恢复失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-prepare-shard-for-recovery-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # 准备分片恢复失败 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [列出密钥失败 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-list-keys-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.17 1. 错误异常的基本描述 # 列出密钥失败 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [创建或更新摄入管道](https://easysearch.cn/knowledge-base/easysearch_api/create-or-update-ingest-pipeline/): 摄入管道（Ingest Pipeline）是 Easysearch 中用于在文档索引之前预处理文档的机制。通过定义一系列处理器（processors），可以在数据被索引之前对其进行转换、丰富和规范化。 API # PUT /_ingest/pipeline/{id} API 的作用 # 创建新的摄入管道或更新已存在的管道。管道的主要功能包括： 数据转换：重命名字段、修改字段值、提取数据等 数 … - [加入集群超时配置](https://easysearch.cn/knowledge-base/easysearch_config/discovery.zen.join_timeout/): 配置项作用 # discovery.zen.join_timeout 配置项用于控制节点加入集群时的超时时间。 当节点尝试加入现有集群时，如果在此时间内未收到响应或完成加入过程，则视为加入失败。 配置项属性 # 配置路径: discovery.zen.join_timeout 数据类型: TimeValue（时间值） 默认值: ping_timeout × 20（默认 60 秒） 最小值: … - [多字段中不允许使用 copy_to —— 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/copy-to-in-multi-fields-is-not-allowed-found-the-copy-to-in-field-name-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.1 1. 错误异常的基本描述 # 多字段中不允许使用 copy_to — 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [字段发现未知形状 Circle - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/field-fieldname-found-and-unknown-shape-circle-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.0-7.6 1. 错误异常的基本描述 # Field [fieldName] found and unknown shape Circle 说明 Elasticsearch 已经识别到目标字段，但在把查询形状转换成 Lucene Query 时，遇到了当前实现不认识或不支持的 Circle 形状。 这通常不是字段不存在，而是 传入了当前版本不支持的几何类型。 常见现象 # … - [字段名称不能设置 store = true - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/the-field-name-cannot-have-store-true-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.9-7.1 1. 错误异常的基本描述 # 字段名称不能设置 store = true 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [安全索引至少有一个主分片不可用 – 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/at-least-one-primary-shard-for-the-security-index-is-unavailable-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.17（含 X-Pack Security 开启场景） 1. 错误说明 # at least one primary shard for the security index is unavailable 表示 Elasticsearch 的 安全索引（.security 或 .security-7） 至少有一个主分片处于不可用状态，导致安全模块无法正常读取或写入安全配置 … - [异步搜索最大运行时间](https://easysearch.cn/knowledge-base/easysearch_config/async_search.max_search_running_time/): 配置项作用 # async_search.max_search_running_time 配置项限制异步搜索请求的最长运行时间。当异步搜索的运行时间超过此限制时，搜索将被自动终止，以防止长时间运行的搜索消耗过多资源。 配置项类型 # 该配置项为动态配置，可以在运行时通过集群更新 API 进行修改，无需重启节点。 默认值 # 12h（12小时） 是否必需 # 可选配置项 取值范围 # 正数 … - [当用户尝试调整索引大小时不允许的操作 – 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/resize-requests-are-not-allowed-for-users-when-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # 当用户尝试调整索引大小时不允许的操作 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法消费OpenID Connect响应 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-consume-the-openid-connect-response-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.2-8.9 1. 错误异常的基本描述 # 无法消费OpenID Connect响应 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [查询阶段执行失败 (query_phase_execution_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/query_phase_execution_exception/): 为什么这个错误发生 # query_phase_execution_exception 表示搜索的查询阶段失败，该阶段执行实际的查询逻辑。 如何修复 # 1. 验证查询语法 # GET /<index>/_validate/query?explain { "query": { "match": { "field": … - [等待分片移交超时 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/timed-out-waiting-for-relocation-hand-off-to-complete-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 等待分片移交超时 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [等待超时 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/timed-out-waiting-for-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # 等待超时 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返回 400、404、409、429、500 … - [索引墓碑记录大小配置](https://easysearch.cn/knowledge-base/easysearch_config/cluster.indices.tombstones.size/): 配置项作用 # cluster.indices.tombstones.size 配置项控制集群状态中保留的索引墓碑（Tombstones）记录的最大数量。墓碑记录用于标记已删除的索引，确保那些离线期间错过索引删除事件的节点在重新加入集群后能够正确处理这些删除操作。 配置项类型 # 该配置项为静态配置，需要在启动时设置，修改后需要重启节点才能生效。 默认值 # 500 是否必需 # 可选配置 … - [节点故障 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/node-failures-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.6-7.15 1. 错误异常的基本描述 # 节点故障 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [跨集群复制领导者线程池队列大小配置](https://easysearch.cn/knowledge-base/easysearch_config/plugins.replication.leader.thread_pool.queue_size/): 配置项作用 # plugins.replication.leader.thread_pool.queue_size 配置项用于控制领导者复制线程池的队列大小。 配置项属性 # 配置路径: plugins.replication.leader.thread_pool.queue_size 数据类型: Integer（整数） 默认值: 1000 是否可选: 是 作用域: NodeScope（节点 … - [选举停止源 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/election-stopped-source-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.17 1. 错误异常的基本描述 # 选举停止源 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [集群状态提交失败异常 (failed_to_commit_cluster_state_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/failed_to_commit_cluster_state_exception/): 为什么这个错误发生 # failed_to_commit_cluster_state_exception 表示在提交集群状态（cluster state）时失败。集群状态包含了集群的所有元数据，如索引、节点、分片分配等信息，需要在集群的所有主节点间达成一致。 这个错误可能由以下原因引起： 集群状态冲突：在提交集群状态时，状态被其他修改操作改变 主节点选举问题：主节点选举过程中的冲突 网络分区： … - [E getMessage – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/e-getmessage-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # E getMessage 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Expected map for property fields on field propNode or – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/expected-map-for-property-fields-on-field-propnode-or-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # Expected map for property fields on field propNode or 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日 … - [Management 线程池最大大小配置](https://easysearch.cn/knowledge-base/easysearch_config/thread_pool.management.max/): 配置项作用 # thread_pool.management.max 配置项用于控制管理线程池的最大线程数。 配置项属性 # 配置路径: thread_pool.management.max 数据类型: Integer（整数） 默认值: 5 是否可选: 是 作用域: NodeScope（节点级别） 动态更新: 是（可以动态更新，无需重启） 配置建议 # 默认配置 # … - [Transport TCP 无延迟配置](https://easysearch.cn/knowledge-base/easysearch_config/transport.tcp.no_delay/): 配置项作用 # transport.tcp.no_delay 配置项用于控制是否禁用 Nagle 算法以减少延迟。 配置项属性 # 配置路径: transport.tcp.no_delay 数据类型: Boolean（布尔值） 默认值: true 是否可选: 是 作用域: NodeScope（节点级别） 动态更新: 否（需要重启节点生效） 配置建议 # 默认配置 # … - [Unknown numeric property [fieldName] - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unknown-numeric-property-fieldname-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # unknown numeric property [fieldName] 是 Elasticsearch 在解析请求体时抛出的 ElasticsearchParseException 异常，表示当前请求中包含了一个无法识别的数值类型属性。该异常最常出现在 Graph API 的探索请求（Graph Explore API）解析过程中，但 … - [Voting only node skipping publication to - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/voting-only-node-skipping-publication-to-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.3-8.9 1. 错误异常的基本描述 # Voting only node skipping publication to 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判 … - [不再是主节点导致任务失败 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/no-longer-master-failing-t-source-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.3-8.7 1. 错误异常的基本描述 # 不再是主节点导致任务失败 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [不可序列化传输异常 (not_serializable_transport_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/not_serializable_transport_exception/): 为什么这个错误发生 # not_serializable_transport_exception 表示在传输层尝试序列化不可序列化的对象时失败。当需要通过网络传输的对象无法被序列化时抛出此异常。 这个错误可能由以下原因引起： 自定义对象未实现序列化：自定义类未实现 Writeable 接口 不可序列化的字段：对象包含不可序列化的字段类型 循环引用：对象存在循环引用 第三方库对象：使用了不支持序 … - [分片恢复速率限制配置](https://easysearch.cn/knowledge-base/easysearch_config/indices.recovery.max_bytes_per_sec/): 配置项作用 # indices.recovery.max_bytes_per_sec 配置项限制分片恢复（Recovery）过程中的网络传输速率，用于控制节点间数据恢复的带宽使用，防止恢复过程占用过多网络资源影响正常业务。 配置项类型 # 该配置项为动态配置，可以在运行时通过集群设置 API 进行修改。 默认值 # 40mb 是否必需 # 可选配置项（有默认值） 取值范围 # 0b（无限 … - [删除快照失败 snapshotId - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-delete-snapshot-snapshotid-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.7 1. 错误异常的基本描述 # failed to delete snapshot [snapshotId] 表示删除请求已经进入仓库实现层，Elasticsearch 在列举索引容器、删除分片快照元数据或处理仓库根目录 blob 时抛出了异常，最终包装为 RepositoryException 返回。 这说明问题发生在“真正删仓库内容”的过程中， … - [刷盘线程池配置](https://easysearch.cn/knowledge-base/easysearch_config/thread_pool.flush/): 配置项作用 # thread_pool.flush 相关配置项控制用于执行刷盘（Flush）操作的线程池。刷盘操作将内存中的段数据写入磁盘，确保持久化。该线程池采用伸缩线程池类型。 配置项类型 # 该配置项为静态配置，需要在启动时设置，修改后需要重启节点才能生效。 默认值 # thread_pool.flush.core: 1 thread_pool.flush.max: … - [同义词集 synonymsSetId 未找到 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/synonym-set-synonymssetid-not-found-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.9-8.9 1. 错误异常的基本描述 # 同义词集 synonymsSetId 未找到 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [名为 name 的自动伸缩策略不存在 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/autoscaling-policy-with-name-name-does-not-exist-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.8-8.9 1. 错误异常的基本描述 # 名为 name 的自动伸缩策略不存在 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [命令不支持指定字段 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/command-does-not-support-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 命令不支持指定字段 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [字段名试图覆盖时间序列指标 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/field-name-attempted-to-shadow-a-time-series-metric-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.17-8.9 1. 错误异常的基本描述 # Field [...] attempted to shadow a time_series_metric 是 Elasticsearch 在处理时间序列（time series）索引时抛出的字段映射冲突异常。该错误表示你正在尝试定义一个新字段，其名称与已有的时间序列指标字段重名，但字段类型或配置不兼容，导致 Elasticsearch … - [对于缺少事件查询的序列必须指定 maxspan 参数，但未找到 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/maxspan-is-required-for-sequences-with-missing-events-queries-found-none-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.9-8.9 1. 错误异常的基本描述 # 对于缺少事件查询的序列必须指定 maxspan 参数，但未找到 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [异步搜索通用线程池保活时间配置](https://easysearch.cn/knowledge-base/easysearch_config/thread_pool.async_search_generic.keep_alive/): 配置项作用 # thread_pool.async_search_generic.keep_alive 配置项用于控制异步搜索通用线程池中弹性线程的保活时间。 当线程数超过核心线程数（core）时，空闲的弹性线程在指定时间后会被回收，释放系统资源。 配置项属性 # 配置路径: thread_pool.async_search_generic.keep_alive 数据类型: … - [当前上下文中没有可用的用户 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/there-is-no-user-available-in-the-current-context-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.7-8.9 1. 错误异常的基本描述 # 当前上下文中没有可用的用户 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [快照不存在 (snapshot_missing_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/snapshot_missing_exception/): 为什么这个错误发生 # snapshot_missing_exception 表示请求的快照在仓库中不存在。 这个错误可能由以下原因引起： 快照名称拼写错误：请求中的快照名称输入错误 快照被删除：快照已被删除 仓库名称错误：快照存在于其他仓库中 快照未完成：快照创建还在进行中 大小写不匹配：快照名称区分大小写 仓库位置变更：仓库位置变更后快照不可用 如何修复这个错误 # 1. … - [拒绝加入，因为此节点尚未收到其初始配置 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/rejecting-join-since-this-node-has-not-received-its-initial-configuration-yet-how-to-solve-this-elasticsearch-exception/): 适用版本： 7-8.9 1. 错误异常的基本描述 # 拒绝加入，因为此节点尚未收到其初始配置 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [指定ID的Watch不存在](https://easysearch.cn/knowledge-base/elasticsearch_error/watch-with-id-does-not-exist-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 指定ID的Watch不存在 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [操作仅在分片状态为特定值时被允许 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/operation-only-allowed-when-shard-state-is-one-of-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # 操作仅在分片状态为特定值时被允许 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无效授权 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/invalid-grant-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # 无效授权 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返回 400、404、409、429、500 … - [无法解析事件 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unable-to-parse-the-event-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.8-8.9 1. 错误异常的基本描述 # 无法解析事件 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [未提供父文档ID——文档内外均未指定——如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/no-parent-id-provided-not-within-the-document-and-not-externally-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-6.8 1. 错误异常的基本描述 # 未提供父文档ID——文档内外均未指定— 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [源数据过滤错误 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/error-filtering-source-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.5 1. 错误异常的基本描述 # 源数据过滤错误 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [索引主分片数配置](https://easysearch.cn/knowledge-base/easysearch_config/config_index.number_of_shards/): 配置项作用 # index.number_of_shards 配置项指定索引的主分片数量。主分片是索引数据的水平切分单位，每个主分片是一个独立的 Lucene 索引。此配置在索引创建时设置，创建后无法修改。 配置项类型 # 该配置项为静态配置，只能在创建索引时设置，创建后无法修改。 默认值 # 1 是否必需 # 可选配置项（有默认值） 取值范围 # 1 ~ 1024（可通过系统属性调整） … - [缺少字段名称的必需参数dims - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/missing-required-parameter-dims-for-field-name-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.1-8.9 1. 错误异常的基本描述 # 缺少字段名称的必需参数dims 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [节点 nodeID 失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-node-nodeid-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 节点 nodeID 失败 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [获取索引映射](https://easysearch.cn/knowledge-base/easysearch_api/get-index-mapping/): 获取索引的映射（mapping）定义，查看字段结构、类型和配置。 API # GET /{index}/_mapping GET /_mapping GET /{index}/_mapping/{type} GET /_mapping/{type} HEAD /{index}/_mapping/{type} API 的作用 # 该 API 用于获取索引的映射信息，可以查看： 字段名称和数据类 … - [解析双精度设置失败 – setting 使用值 sValue – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-double-setting-setting-with-value-svalue-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 解析双精度设置失败 – setting 使用值 sValue 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [解析记录失败 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-record-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 解析记录失败 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [读取搜索请求时出现未预期的布尔字段 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-read-search-request-unexpected-boolean-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.x-8.x 1. 问题含义 # could not read search request. unexpected boolean field [field] 表示 Elasticsearch 在读取搜索请求顶层字段时，遇到了一个布尔值字段，但该字段名不在允许列表里。 从附带源码可见，布尔值分支只接受特定字段，例如 rest_total_hits_as_int。如果你在请求体顶 … - [collapse 字段不存在映射 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/no-mapping-found-for-field-in-order-to-collapse-on-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.4 1. 错误异常的基本描述 # Elasticsearch 在处理折叠字段时，如果找不到对应映射，会直接报错： no mapping found for `field` in order to collapse on 这类错误常见于字段名写错、索引模板变更后字段消失，或跨索引查询时某些索引没有该字段。 2. 为什么会发生这个错误 # collapse 必须建立在明确 … - [failed to load settings - 自定义设置文件加载失败](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-load-settings-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Failed to load settings 出现在通过 Settings.builder().loadFromPath(customSettingsYamlFile).build() 读取自定义配置文件的路径里。源码上下文很明确：失败点发生在 loadFromPath，属于文件读取或配置解析阶段，而不是后续业务使用阶段。 这不是业务 … - [Geometries必须是geojson对象的数组 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/geometries-must-be-an-array-of-geojson-objects-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Geometries必须是geojson对象的数组 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返 … - [Invalid dynamic name expression - date math 占位符未闭合如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/invalid-dynamic-name-expression-date-math-placeholder-is-open-ended-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # invalid dynamic name expression [expr]. date math placeholder is open ended 表示 Elasticsearch 在解析动态索引名时，发现 date math 占位符开了头但没有正确结束。Elasticsearch 支持在索引名中使用 date math 表达式来 … - [Key 必须是路径中的最后一个元素 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/key-must-be-the-last-element-in-the-path-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Key 必须是路径中的最后一个元素 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Lucene 段信息跟踪配置](https://easysearch.cn/knowledge-base/easysearch_config/node.enable_lucene_segment_infos_trace/): 配置项作用 # node.enable_lucene_segment_infos_trace 配置项用于控制是否启用 Lucene SegmentInfos 的详细跟踪日志输出。 当启用时，会将 Lucene 段文件（segments file）的读取、写入、加载等详细调试信息输出到标准输出（System.out），主要用于故障排查和性能分析。 配置项属性 # 配置路径: … - [NAME 未找到类型映射 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/name-no-mapping-found-for-type-type-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-6.8 1. 错误异常的基本描述 # NAME 未找到类型映射 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Rollup 搜索重试次数配置](https://easysearch.cn/knowledge-base/easysearch_config/rollup.search.backoff_count/): 配置项作用 # rollup.search.backoff_count 配置项用于控制Rollup 搜索操作失败时的最大重试次数。 当 Rollup 搜索操作因网络问题、节点不可用或其他临时性错误失败时，系统会根据此配置的值决定最多重试多少次。 配置项属性 # 配置路径: rollup.search.backoff_count 数据类型: Integer（整数） 默认值: 5 是否可选: … - [Search 线程池自动队列帧大小配置](https://easysearch.cn/knowledge-base/easysearch_config/thread_pool.search.auto_queue_frame_size/): 配置项作用 # thread_pool.search.auto_queue_frame_size 配置项用于控制搜索线程池自动队列调整的帧大小。 这是用于基于 Little’s Law 自动调整队列大小时收集统计信息的任务数量。 配置项属性 # 配置路径: thread_pool.search.auto_queue_frame_size 数据类型: Integer（整数） 默认 … - [source字段不可搜索——如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/the-source-field-is-not-searchable-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # source字段不可搜索— 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Term查询 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/term-query-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.3-8.9 1. 错误异常的基本描述 # Term查询 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Token 已过期 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/token-expired-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Token 已过期 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Unknown key for create index - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unknown-key-for-create-index-how-to-solve-this-elasticsearch-exception/): 适用版本： 7-8.9 1. 错误异常的基本描述 # unknown key for create index 是 Elasticsearch 在解析创建索引请求时抛出的 ElasticsearchParseException 异常。当请求体（Request Body）中包含无法识别的顶层键（key）时，Elasticsearch 无法将其映射到已知的配置项，从而抛出此异常并拒绝创建索引。 常 … - [watch 的 input 缺少必填 request 字段 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-input-for-watch-missing-required-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # could not parse [input] for watch [<id>]. missing required [request] field 是 Elasticsearch Watcher 功能在解析 Watch 定义时抛出的异常。该错误表示 Watcher 的 input 部分已经通过了初步的结构解析，但在最终构 … - [主节点慢任务日志阈值配置](https://easysearch.cn/knowledge-base/easysearch_config/cluster.service.slow_master_task_logging_threshold/): 配置项作用 # cluster.service.slow_master_task_logging_threshold 配置项控制主节点上执行的集群管理任务（如集群状态更新、分片分配决策等）执行时间的日志记录阈值。当任务执行时间超过此阈值时，会记录警告日志，用于识别主节点性能瓶颈。 配置项类型 # 该配置项为动态配置，可以在运行时通过集群设置 API 进行修改。 默认值 # 10s（10秒） … - [使用 fields 选项时无法禁用 stored_fields – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/stored-fields-cannot-be-disabled-when-using-the-fields-option-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.1-8.9 1. 错误异常的基本描述 # 使用 fields 选项时无法禁用 stored_fields 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [分片分配启用配置](https://easysearch.cn/knowledge-base/easysearch_config/cluster.routing.allocation.enable/): 配置项作用 # cluster.routing.allocation.enable 配置项控制集群中分片（shard）的分配行为，包括新分片的分配和现有分片的重新分配。此配置用于控制分片在节点之间的移动和分配策略。 配置项类型 # 该配置项为动态配置，可以在运行时通过集群设置 API 进行修改。 默认值 # all（允许所有分片分配） 是否必需 # 可选配置项 配置值说明 # 值 … - [删除模板未被确认 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/deleting-template-was-not-acknowledged-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-6.8 1. 错误异常的基本描述 # 删除模板未被确认 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [地址列表字段必须是字符串或地址对象数组 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-field-as-address-list-field-must-either-be-a-string-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # could not parse [field] as address list. field must either be a string ... or an array of objects representing addresses 表示 Elasticsearch 在解析邮件地址列表字段时，发现该字段既不是字符串，也不是地址 … - [异步搜索减少部分结果时出错 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/async-search-error-while-reducing-partial-results-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.8-8.9 1. 错误异常的基本描述 # async search error while reducing partial results 是 Elasticsearch 在执行**异步搜索（Async Search）**过程中，对多个分片返回的部分结果进行归并（reduce）阶段失败时报出的异常。 异步搜索允许客户端提交一个查询，Elasticsearch 在后台持续执行， … - [快照引擎失败异常 (snapshot_failed_engine_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/snapshot_failed_engine_exception/): 为什么这个错误发生 # snapshot_failed_engine_exception 表示在创建引擎快照时失败。引擎快照是用于持久化引擎状态的操作，通常用于事务日志检查点等。 这个错误可能由以下原因引起： 引擎状态错误：引擎处于不支持快照的状态 事务日志问题：事务日志检查点失败 磁盘 IO 错误：磁盘写入错误 磁盘空间不足：磁盘空间不足以创建快照 并发操作冲突：快照过程中有冲突的操作 文件 … - [恢复失败 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-recovery-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 恢复失败 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [文本查询未指定文本 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/no-text-specified-for-text-query-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 文本查询未指定文本 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法在未启用 doc_values 的字段上使用折叠 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-collapse-on-field-field-without-doc-values-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.4 1. 错误异常的基本描述 # 当搜索请求里使用了 collapse，但目标字段没有 doc_values 时，Elasticsearch 会抛出类似下面的异常： cannot collapse on field `field` without `doc_values` 这类错误通常出现在查询阶段，请求会直接失败，常见返回码是 400。 2. 为什么会发生这个错误 # … - [无法对字段别名执行操作 – 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-verb-to-a-field-alias-mapper-name-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.1-8.1 1. 错误异常的基本描述 # 无法对字段别名执行操作 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [未找到可修改设置的Watcher – 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/no-watches-found-on-which-to-modify-settings-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.8-8.9 1. 错误异常的基本描述 # 未找到可修改设置的Watcher 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [未知的上下文类型 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unknown-context-type-type-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.17 1. 错误异常的基本描述 # 未知的上下文类型 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [本地节点发现 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/local-node-found-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # 本地节点发现 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返回 400、404、409、429、500 … - [查询指定任务](https://easysearch.cn/knowledge-base/easysearch_api/get-specific-task/): 此 API 用于获取集群中指定任务的详细信息。 API # GET /_tasks/{task_id} API 的作用 # 返回集群中指定任务的详细信息和当前状态。任务是在集群中运行的任何操作，例如搜索、索引、重建索引等。通过任务 ID，可以获取特定任务的： 任务状态：当前运行状态 执行时间：任务开始时间和运行时长 任务类型：任务的类型和操作 可取消性：任务是否可以被取消 执行节点：任务执行 … - [格式错误期望 – 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/incorrect-format-expecting-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # 格式错误期望 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [节点不存在 (no_such_node_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/no_such_node_exception/): 为什么这个错误发生 # no_such_node_exception 表示引用的节点 ID 在集群中不存在。节点可能已离线或被删除。 如何修复 # 1. 检查集群节点 # GET /_cat/nodes?v 2. 验证节点 ID # GET /_nodes/<node_id> 3. 更新客户端配置 # 更新客户端节点列表使用可用节点。 预防措施 # 使用多个节点配置 实现 … - [节点数据角色配置](https://easysearch.cn/knowledge-base/easysearch_config/node.data/): 配置项作用 # node.data 配置项控制节点是否可以作为数据节点，即是否可以持有索引数据。 是否可选 # 是 默认值 # true (可作为数据节点) 配置项类型 # 静态配置 - 需要重启节点才能生效 配置格式 # # 默认配置（数据节点） node.data: true # 禁用数据角色 node.data: false 节点类型说明 # node.data … - [读取 indices options 时出现未预期的对象字段并指明字段名 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-read-indices-options-unexpected-object-field-currentfieldname-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.x-8.x 1. 问题含义 # could not read indices options. unexpected object field [currentFieldName] 与普通的 unexpected object field 本质相同，都是在解析 indices_options 时遇到了不应出现的对象值。 区别在于这里的日志会更明确地带出具体字段名，因此定位通常更 … - [达到最大运行作业容量 maxAllowedRunningJobs - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/max-running-job-capacity-maxallowedrunningjobs-reached-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # 达到最大运行作业容量 maxAllowedRunningJobs 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [could not parse slack message unknown field - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-slack-message-unknown-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # could not parse slack message. unknown field [field] 是 Elasticsearch Watcher 在解析 Slack 消息配置时抛出的异常。当 Slack 消息对象中出现当前解析器不支持的字段时，就会触发此错误。 此错误通常发生在 Slack action 的 message 对象 … - [Expected map for runtime field fieldName definition but got a – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/expected-map-for-runtime-field-fieldname-definition-but-got-a-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.11-8.9 1. 错误异常的基本描述 # Expected map for runtime field [fieldName] definition but got a ... 是 Elasticsearch 在解析索引 mapping 中 runtime 字段定义时抛出的映射解析异常。该错误表示 Elasticsearch 预期 runtime … - [Generic 线程池最大大小配置](https://easysearch.cn/knowledge-base/easysearch_config/thread_pool.generic.max/): 配置项作用 # thread_pool.generic.max 配置项用于控制通用线程池的最大线程数。 这是线程池能够创建的最大线程数量上限。 配置项属性 # 配置路径: thread_pool.generic.max 数据类型: Integer（整数） 默认值: 4 × CPU核心数，最大不超过 512 是否可选: 是 作用域: NodeScope（节点级别） 动态更新: 是（可以动态更 … - [HTTP 请求体最大长度配置](https://easysearch.cn/knowledge-base/easysearch_config/http.max_content_length/): 配置项作用 # http.max_content_length 配置项限制 HTTP 服务器接受的最大请求体大小，防止过大的请求耗尽服务器内存。 是否可选 # 是 默认值 # 100mb 配置项类型 # 静态配置 - 需要重启节点才能生效 配置格式 # # 默认配置 http.max_content_length: 100mb # … - [Include/Exclude 子句中出现未知参数 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unknown-parameter-in-include-exclude-clause-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.16-8.9 1. 错误异常的基本描述 # Include/Exclude 子句中出现未知参数 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能 … - [Labels hint 支持字符串或字符串列表作为其值 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/labels-hint-supports-either-string-or-list-of-strings-as-its-value-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.3-8.9 1. 错误异常的基本描述 # Labels hint 支持字符串或字符串列表作为其值 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可 … - [ML内存跟踪器刷新期间节点停止作为主节点——如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/node-ceased-to-be-master-during-ml-memory-tracker-refresh-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.12-8.9 1. 错误异常的基本描述 # ML内存跟踪器刷新期间节点停止作为主节点— 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Search 线程池队列大小配置](https://easysearch.cn/knowledge-base/easysearch_config/thread_pool.search.queue_size/): 配置项作用 # thread_pool.search.queue_size 配置项用于控制搜索线程池的初始队列大小。 对于 FIXED_AUTO_QUEUE_SIZE 类型的线程池，这是队列的初始容量，实际大小会根据负载动态调整。 配置项属性 # 配置路径: thread_pool.search.queue_size 数据类型: Integer（整数） 默认值: 1000 是否可选: 是 作 … - [Span multi 查询不支持 currentFieldName – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/span-multi-query-does-not-support-currentfieldname-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Span multi 查询不支持 currentFieldName 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Unknown field name [currentFieldName] - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unknown-field-name-currentfieldname-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # unknown field name [currentFieldName] 是 Elasticsearch 在解析 JSON/YAML 请求体或配置文件时抛出的 ElasticsearchParseException。当 XContentParser 在解析某个对象时，遇到一个不在预期字段列表中的字段名，就会触发此异常。 该异常的本质 … - [XML元素无法反序列化为SAML类型](https://easysearch.cn/knowledge-base/elasticsearch_error/xml-element-cannot-be-unmarshalled-to-saml-type-no-unmarshaller-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.7-7.15 1. 错误异常的基本描述 # XML元素无法反序列化为SAML类型 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [不能同时指定 region 和 endpoint - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/you-must-not-specify-both-region-and-endpoint-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.4-8.17 1. 错误异常的基本描述 # you must not specify both region and endpoint 是 Elasticsearch 在执行 S3 快照仓库的 cleanup 操作时抛出的参数校验异常。该错误表示在仓库配置中同时指定了 region 和 endpoint 两个互斥参数，Elasticsearch 无法判断应优先采用哪种服务定位方 … - [几何体未包含 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/geometries-not-included-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 几何体未包含 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [分片仅在激活状态时才允许操作 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/operation-only-allowed-when-shard-is-active-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 分片仅在激活状态时才允许操作 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [如果你想使用Azure存储库，需要定义客户端配置 – 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/if-you-want-to-use-an-azure-repository-you-need-to-define-a-client-configuration-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # If you want to use an azure repository, you need to define a client configuration 表示 Elasticsearch 已经加载了 Azure 仓库相关逻辑，但在刷新或读取 Azure client 配置时发现根本没有可用的客户端设置。没有 client 配 … - [恢复失败——如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/restore-failed-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # restore failed 表示某个分片已经通过了前置快照校验，并进入恢复执行阶段，但在 prepareForIndexRecovery、openEngineAndRecoverFromTranslog、补齐 sequence number gaps 或 finalizeRecovery 等步骤中出现异常， … - [无主节点阻塞配置](https://easysearch.cn/knowledge-base/easysearch_config/cluster.no_master_block/): 配置项作用 # cluster.no_master_block 配置项指定当集群没有主节点（Master）时，对哪些操作进行阻塞。这是一个重要的安全配置，用于在主节点故障期间防止数据不一致或脑裂情况下的数据损坏。 配置项类型 # 该配置项为动态配置，可以在运行时通过集群设置 API 进行修改。 默认值 # write（阻塞写操作） 是否必需 # 可选配置项（有默认值） 可选值 # … - [无效的 JWT typ 头部 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/invalid-jwt-typ-header-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # 无效的 JWT typ 头部 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无效的别名名称 (invalid_alias_name_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/invalid_alias_name_exception/): 为什么这个错误发生 # invalid_alias_name_exception 表示使用了无效的别名名称。 如何修复 # 1. 遵循命名规则 # 不能以 _ 开头 不能包含特殊字符 不能包含空格 2. 使用正确的别名 # POST /_aliases { "actions": [{ "add": { "index": … - [无法为快照创建分片克隆 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/can-t-create-clone-of-shardid-for-snapshot-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.10-8.9 1. 错误异常的基本描述 # 这条 Can't create clone of [shardId] for snapshot [target] 来自 shard snapshot clone 流程中的源快照定位逻辑。源码会在 shard metadata 里扫描可用的 snapshot 记录，尝试找到 source snapshot 对应的文件集合； … - [无法删除正在进行快照的索引 – 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-delete-indices-that-are-being-snapshotted-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # Cannot delete indices that are being snapshotted 表示你试图删除的索引当前仍被快照流程占用。Elasticsearch 会先检查待删除索引是否包含在 SnapshotsService.snapshottingIndices(...) 的结果中；如果命中， … - [无法解析持续时间 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-parse-duration-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.17 1. 错误异常的基本描述 # 无法解析持续时间 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法解析监视器状态，期望字段保存日期值（Could not parse watch status. expecting field to hold a date value）- 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-watch-status-expecting-field-to-hold-a-date-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.x 1. 错误异常的基本描述 # could not parse watch status. expecting field [...] to hold a date value; found [...] instead 表示 Watcher 期望某个状态字段保存日期，但实际读到的 token 不是可解析的日期值。 从源码片段看，典型字段包括 last_checked … - [无法解析类型为 contentType 的 fieldType 字段 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-field-fieldtype-name-of-type-contenttype-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.13-8.7 1. 错误异常的基本描述 # 无法解析类型为 contentType 的 fieldType 字段 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 … - [未知的 URL 协议 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unknown-url-protocol-from-url-url-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # 未知的 URL 协议 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [模板不能为空 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/template-must-not-be-null-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 模板不能为空 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [此缓存评分器实现仅实现了score和docID - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/this-caching-scorer-implementation-only-implements-score-and-docid-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-6.8 1. 错误异常的基本描述 # 此缓存评分器实现仅实现了score和docID 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [清除索引缓存](https://easysearch.cn/knowledge-base/easysearch_api/clear-index-cache/): 清理一个或多个索引的缓存，释放内存资源。 API # POST /_cache/clear POST /{index}/_cache/clear API 的作用 # 该 API 用于清理索引的缓存，可以释放内存资源。支持清理以下类型的缓存： 缓存类型 描述 query cache 查询缓存，存储查询执行的中间结果 field data cache 字段数据缓存，存储聚合和排序 … - [解析More Like This项失败 - 字段fields必须是数组 – 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-more-like-this-item-field-fields-must-be-an-array-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.16-7.17 1. 错误异常的基本描述 # failed to parse More Like This item. field [fields] must be an array 是 Elasticsearch 在执行 More Like This（MLT）查询时，因请求体参数格式不符合解析要求而抛出的异常。该错误发生在 DSL 解析阶段，意味着 fields 字段的值不是 … - [设置监控失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-set-monitoring-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.11-8.9 1. 错误异常的基本描述 # 设置监控失败 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [请求缓存配置](https://easysearch.cn/knowledge-base/easysearch_config/indices.requests.cache.size/): 配置项作用 # indices.requests.cache 配置项控制请求缓存（Request Cache）的 JVM 堆内存大小。请求缓存用于缓存分片级别的查询请求结果（主要是 count 请求），提高重复查询的性能。 配置项类型 # 该配置项为静态配置，需要在启动时设置，修改后需要重启节点才能生效。 默认值 # 1%（JVM 堆内存的 1%） 是否必需 # 可选配置项（有默认值） 配 … - [通用异常 (exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/exception/): 为什么这个错误发生 # exception 是 Easysearch 的基础异常类，是所有其他 Easysearch 异常的父类。当返回此异常时，通常表示一个通用的错误情况。 这个异常是 EasysearchException 基类，包含了所有 Easysearch 相关异常的共同属性： 错误类型（type） 错误原因（reason） 导致错误的原始异常（caused_by） 相关的索引、分片 … - [集群状态发布超时配置](https://easysearch.cn/knowledge-base/easysearch_config/discovery.zen.publish_timeout/): 配置项作用 # discovery.zen.publish_timeout 配置项用于控制主节点发布集群状态的完整超时时间，包括发送和提交两个阶段。 当主节点向集群其他节点发布新的集群状态时，必须等待足够数量的节点确认接收。此配置定义了这个等待过程的最长时间。 配置项属性 # 配置路径: discovery.zen.publish_timeout 数据类型: TimeValue（时间值） 默 … - [could not parse month times expected an object but found - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-month-times-expected-an-object-but-found-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # could not parse month times. expected an object; but found [token] 是 Elasticsearch Watcher 在解析 monthly schedule（月度调度）配置时抛出的异常。当 times 字段的值不是解析器期望的对象结构时，就会触发此错误。 monthly … - [HTTP 绑定地址配置](https://easysearch.cn/knowledge-base/easysearch_config/http.bind_host/): 配置项作用 # http.bind_host 配置项指定 HTTP 服务实际绑定的网络接口 IP 地址，决定在哪里监听 HTTP 连接。 是否可选 # 是 默认值 # [] (空列表，依次回退到 http.host、network.bind_host、network.host) 配置项类型 # 静态配置 - 需要重启节点才能生效 配置格式 # # 绑定到特定 IP … - [HTTP 请求跟踪包含配置](https://easysearch.cn/knowledge-base/easysearch_config/http.tracer.include/): 配置项作用 # http.tracer.include 配置项用于指定需要被跟踪记录的 HTTP 请求 URI 模式列表。 当启用 HTTP 请求跟踪时，只有匹配此配置中任一模式的请求才会被记录到 TRACE 级别的日志中。 配置项属性 # 配置路径: http.tracer.include 数据类型: List<String>（字符串列表） 默认值: []（空列表，表示不限制） … - [Max children 仅支持嵌套排序的顶层 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/max-children-is-only-supported-on-top-level-of-nested-sort-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # Max children 仅支持嵌套排序的顶层 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Reducer 配置中出现意外 token - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unexpected-token-token-in-reducername-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Unexpected token TOKEN in [reducerName] 是 Elasticsearch 在解析聚合（aggregation）DSL 时抛出的 ParsingException。该错误专门出现在 pipeline aggregation（管道聚合） 或 reducer 配置阶段，表示 Elasticsearch 在 … - [rescore 不支持该字段 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/rescore-doesn-t-support-fieldname-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 当 rescore 配置中出现不被支持的字段名时，解析器会抛出： rescore doesn't support [fieldName] 2. 为什么会发生这个错误 # 这个错误不是字段 mapping 不支持，而是 rescore 配置对象里出现了非法字段。源码在解析 rescore 顶层时，只接受少量固定字段， … - [Search 线程池大小配置](https://easysearch.cn/knowledge-base/easysearch_config/thread_pool.search.size/): 配置项作用 # thread_pool.search.size 配置项用于控制搜索线程池的线程数量。 这是处理搜索请求的核心线程池，直接影响查询性能。 配置项属性 # 配置路径: thread_pool.search.size 数据类型: Integer（整数） 默认值: (CPU核心数 × 3) / 2 + 1 是否可选: 是 作用域: NodeScope（节点级别） 动态更新: 否（需要 … - [TermsQueryBuilder NAME 查询需要字段名 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/termsquerybuilder-name-query-requires-a-field-name-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # TermsQueryBuilder NAME 查询需要字段名 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Watcher未正确停止，无法再次启动](https://easysearch.cn/knowledge-base/elasticsearch_error/watcher-did-not-stop-properly-so-cannot-start-up-again-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-6.8 1. 错误异常的基本描述 # Watcher未正确停止，无法再次启动 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [仅需要两个值 lon lat - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/only-two-values-lon-lat-expected-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 仅需要两个值 lon lat 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [使用令牌名称验证服务账户失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-authenticate-service-account-with-token-name-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.13-7.15 1. 错误异常的基本描述 # 使用令牌名称验证服务账户失败 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [动作传输异常 (action_transport_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/action_transport_exception/): 为什么这个错误发生 # action_transport_exception 表示在执行传输层动作（action）时发生失败。这是一个传输层异常，通常发生在节点间通信时尝试调用远程节点的某个操作时。 这个错误可能由以下原因引起： 网络连接问题：节点间的网络连接中断或不稳定 远程节点故障：目标节点崩溃、宕机或无响应 超时：操作执行时间超过配置的超时限制 远程节点资源不足：目标节点 CPU、内存或 … - [发现带有错误参数的transform持久任务ID – 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/found-transform-persistent-task-id-with-incorrect-params-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.5-7.5 1. 错误异常的基本描述 # 发现带有错误参数的transform持久任务ID 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [响应通道请求 getHttpChannel 已关闭 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/response-channel-request-gethttpchannel-closed-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.12-8.9 1. 错误异常的基本描述 # 响应通道请求 getHttpChannel 已关闭 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [国产企业级搜索引擎选型的 5 个关键指标](https://easysearch.cn/knowledge-base/insight/five-key-indicators-for-selecting-domestic-enterprise-search-engines/): 在信创战略持续落地的过程中，越来越多的政企用户开始正视一个现实问题： 企业级搜索引擎，已经从“可选组件”变成了“核心基础设施”。 面对国产化替代的浪潮，市场上“国产搜索”“国产 Elasticsearch 替代方案”层出不穷，但真正进入选型阶段后，很多企业却发现： 看起来“都能用”，但差异并不清晰 短期可跑，长期是否可控存疑 信创验收能过，但业务压力一来就露底 那么，在信创与国产化背景下，到底 … - [在字段 fieldName 上创建查询时出现异常 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/exception-creating-query-on-field-fieldname-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.3-8.9 1. 错误异常的基本描述 # 在字段 fieldName 上创建查询时出现异常 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [嵌套聚合缺少path字段 – 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/missing-path-field-for-nested-aggregation-aggregationname-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 嵌套聚合缺少path字段 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [找不到 Hunspell 字典 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-find-hunspell-dictionary-s-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Could not find hunspell dictionary [locale] 表示 Elasticsearch 在初始化 Hunspell 分析器时，无法在配置的 Hunspell 字典目录中找到对应 locale（语言区域）的字典文件。该异常属于配置类错误，通常发生在索引创建、分析器加载或节点启动阶段，而非查询执行阶段。 常 … - [文档 docId 获取阶段运行错误 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/error-running-fetch-phase-for-doc-docid-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.1-8.5 1. 错误异常的基本描述 # 文档 docId 获取阶段运行错误 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无效的搜索应用程序 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/invalid-search-application-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.9-8.9 1. 错误异常的基本描述 # 无效的搜索应用程序 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法解析指定监视器状态，期望字段保存 Long 值（Could not parse watch status for [watchId]. expecting field to hold a long value）- 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-watch-status-for-expecting-field-to-hold-a-long-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.x 1. 错误异常的基本描述 # could not parse watch status for [watchId]. expecting field [...] to hold a long value; found [...] instead 表示 Elasticsearch 在解析某个具体 watch 的状态文档时，遇到了类型不匹配的问题。 Watcher … - [无法解析显著性启发式算法未知字段 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-significance-heuristic-unknown-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.5 1. 错误异常的基本描述 # failed to parse significance heuristic. unknown field 是 Elasticsearch 在执行 显著性聚合（Significance Aggregation） 时抛出的解析异常。该错误表示在解析 significance_heuristic 配置对象时，遇到了当前解析器无法识别的字段 … - [无法解析监视器条件，期望条件主体是对象（Could not parse condition for watch. expected an object but found）- 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-condition-for-watch-expected-an-object-but-found-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.x 1. 错误异常的基本描述 # could not parse [...] condition for watch [...]. expected an object but found [...] instead 是 Elasticsearch Watcher 在解析监视器（watch）条件时抛出的异常。该错误表示 Watcher 在读取某个条件类型时，预期条件主体 … - [无法调查路径 path - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unable-to-investigate-path-path-how-to-solve-this-elasticsearch-exception/): 适用版本： 7-8.9 1. 错误异常的基本描述 # 无法调查路径 path 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法选择最佳词项 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-select-best-terms-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 无法选择最佳词项 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [更新同义词时出现错误 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/error-updating-synonyms-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.9-8.9 1. 错误异常的基本描述 # 更新同义词时出现错误 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [未找到可执行推理的模型 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/no-model-could-be-found-to-perform-inference-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.12-8.9 1. 错误异常的基本描述 # 未找到可执行推理的模型 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [未指定字段类型 fieldName – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/no-type-specified-for-field-fieldname-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 未指定字段类型 fieldName 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [查询缓存条目数量配置](https://easysearch.cn/knowledge-base/easysearch_config/indices.queries.cache.count/): 配置项作用 # indices.queries.cache.count 配置项控制查询缓存中可存储的最大条目数量。 默认值 # 10000 配置类型 # 动态配置 配置格式 # # 默认配置 indices.queries.cache.count: 10000 # 增加缓存条目数 indices.queries.cache.count: 20000 - [检索角色失败，期望对象但得到了其他类型 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-retrieve-roles-expecting-an-object-but-got-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.17 1. 错误异常的基本描述 # 检索角色失败，期望对象但得到了其他类型 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [管道缺失 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/pipeline-is-missing-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 管道缺失 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返回 400、404、409、429、500 … - [节点未连接异常 (node_not_connected_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/node_not_connected_exception/): 为什么这个错误发生 # node_not_connected_exception 表示尝试向未连接的节点发送消息。这是一个传输层异常，当节点间没有建立连接时发生。 这个错误可能由以下原因引起： 节点未启动：目标节点未运行 网络连接断开：节点间的网络连接中断 连接超时：连接建立超时导致断开 节点离线：目标节点已离开集群 防火墙阻止：防火墙阻止了节点间通信 配置错误：节点地址或端口配置错误 节点重 … - [解析SQL查询](https://easysearch.cn/knowledge-base/easysearch_api/translate-sql-query/): API 状态说明 # 在 Easysearch 中，不存在 GET /_sql/parsed API。 实际存在的 SQL API # Easysearch 中实际存在的 SQL 相关 API 如下： POST /_sql # 执行 SQL 查询的主要端点。 POST /_sql POST /_sql/_explain # 获取 SQL 查询的执行计划。 POST … - [资源重载高频检查间隔配置](https://easysearch.cn/knowledge-base/easysearch_config/resource.reload.interval.high/): 配置项作用 # resource.reload.interval.high 配置项控制高频资源检查的轮询间隔。 默认值 # 如配置名所示 配置类型 # 静态配置 配置格式 # # 默认配置 resource.reload.interval.high: default - [足够的master节点确认集群状态后离开 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/enough-masters-to-ack-sent-cluster-state-left-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # 足够的master节点确认集群状态后离开 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [跨集群复制跟随者分片并发读取器配置](https://easysearch.cn/knowledge-base/easysearch_config/plugins.replication.follower.concurrent_readers_per_shard/): 配置项作用 # plugins.replication.follower.concurrent_readers_per_shard 配置项用于控制跟随者节点上每个分片的并发读取器数量。 配置项属性 # 配置路径: plugins.replication.follower.concurrent_readers_per_shard 数据类型: Integer（整数） 默认值: 2 是否可选: … - [and must be valid double values - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/and-must-be-valid-double-values-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15+ 1. 错误异常的基本描述 # [field] and [LATITUDE] must be valid double values 或 [field] and [LONGITUDE] must be valid double values 是 Elasticsearch 在解析 地理坐标字段（geo_point）时抛出的类型验证错误。当你在索引文档或执行地理查询 … - [became follower - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/became-follower-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.0-8.9 1. 错误异常的基本描述 # became follower 是 Elasticsearch 集群协调层（Coordination Layer）抛出的异常，完整异常类通常为 CoordinationStateRejectedException: became follower。该异常表示当前节点在尝试以候选者（candidate）或领导者（leader）身份处理加入 … - [could not parse message attachment failed to parse field - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-message-attachment-failed-to-parse-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # could not parse message attachment. failed to parse [...] field 是 Elasticsearch Watcher 在解析消息附件（message attachment）时抛出的异常。当 Watcher 尝试解析附件中的模板字段（如 fallback、color 等）时，如果这 … - [Error 错误 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/error-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.16-8.9 1. 错误异常的基本描述 # Error 错误 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [FieldName - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/fieldname-how-to-solve-this-elasticsearch-exception/): 适用版本： 7-7.15 1. 错误异常的基本描述 # FieldName 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Geo point 仅支持 WKT 原语中的 POINT——如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/geo-point-supports-only-point-among-wkt-primitives-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # Geo point 仅支持 WKT 原语中的 POINT— 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [NAME getPreferredName 查询不支持 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/name-getpreferredname-query-does-not-support-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.15-7.15 1. 错误异常的基本描述 # NAME getPreferredName 查询不支持 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接 … - [Refresh 线程池核心大小配置](https://easysearch.cn/knowledge-base/easysearch_config/thread_pool.refresh.core/): 配置项作用 # thread_pool.refresh.core 配置项用于控制索引刷新线程池的核心线程数。 Refresh 线程池用于执行索引刷新操作，将内存中的更改刷新到磁盘，使新文档可被搜索。 配置项属性 # 配置路径: thread_pool.refresh.core 数据类型: Integer（整数） 默认值: 1 是否可选: 是 作用域: NodeScope（节点级别） 动态更 … - [Transform 内部索引重试延迟配置](https://easysearch.cn/knowledge-base/easysearch_config/transform.internal.index.backoff_millis/): 配置项作用 # transform.internal.index.backoff_millis 配置项用于控制Transform 任务在索引操作重试之间的延迟时间。 配置项属性 # 配置路径: transform.internal.index.backoff_millis 数据类型: TimeValue（时间值） 默认值: 1000ms（1 秒） 是否可选: 是 作用域: … - [Unknown key for a token in - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unknown-key-for-a-token-in-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # unknown key for a token in [...] 表示 Elasticsearch 在解析某个对象字段时，读到了当前 token，但这个 token 所在位置不允许出现对应的键或值结构。 从当前页面保留的源码看，它常见于按 token 类型分支解析的配置对象中。示例片段里 parser 只接受少量已知字段， … - [不支持的字段 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unsupported-field-fieldname-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 不支持的字段 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返回 400、404、409、429、500 … - [不知道如何处理 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/does-not-know-how-to-handle-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.14 1. 错误异常的基本描述 # 不知道如何处理 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [为别名请求构建 JSON 失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-build-json-for-alias-request-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Failed to build json for alias request 是 Elasticsearch 在处理别名（Alias）请求时抛出的异常，核心触发点是别名请求中的 filter 字段在被封装为 CompressedXContent 时失败。该异常通常意味着别名请求的 JSON 结构存在问题，而不是别名 API 路由本身的问 … - [主节点配置](https://easysearch.cn/knowledge-base/easysearch_config/node.master/): 配置项作用 # node.master 配置项用于控制节点是否有资格成为主节点（Master-eligible Node）。 主节点是集群的核心，负责集群范围内的管理操作，如创建或删除索引、跟踪哪些节点是集群的一部分、决定分片分配到哪些节点等。 注意：此配置项已被废弃，推荐使用 node.roles 配置来替代。 配置项属性 # 配置路径: node.master 数据类型: … - [分片标记为已重定位，无法安全移动到指定状态 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/shard-is-marked-as-relocated-cannot-safely-move-to-state-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # 分片标记为已重定位，无法安全移动到指定状态 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [字符不能用于转义 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/char-cannot-be-used-for-escaping-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.8 1. 错误异常的基本描述 # 字符不能用于转义 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [对等恢复未找到异常 (peer_recovery_not_found_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/peer_recovery_not_found_exception/): 为什么这个错误发生 # peer_recovery_not_found_exception 表示在查找对等恢复（peer recovery）时失败。对等恢复是指从一个节点向另一个节点复制分片数据的过程。 这个错误可能由以下原因引起： 恢复 ID 无效：指定的恢复 ID 不存在或已过期 目标节点故障：目标节点发生故障或离线 恢复已完成：恢复过程已经完成，状态已清理 恢复被取消：恢复操作被取消 分 … - [异步搜索通用线程池核心大小配置](https://easysearch.cn/knowledge-base/easysearch_config/thread_pool.async_search_generic.core/): 配置项作用 # thread_pool.async_search_generic.core 配置项用于控制异步搜索通用线程池的核心线程数。 核心线程数是线程池中始终保持活跃的线程数量，即使没有任务执行时也不会被回收。异步搜索功能使用此线程池执行管理操作。 配置项属性 # 配置路径: thread_pool.async_search_generic.core 数据类型: Integer（整数） … - [当集群中所有节点的版本为特定版本时才能使用功能状态 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/feature-states-can-only-be-used-when-all-nodes-in-cluster-are-version-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.13-7.13 1. 错误异常的基本描述 # feature_states can only be used when all nodes in cluster are version [...] or higher 表示你在创建或恢复包含 feature_states 的快照时，当前集群里至少有一个节点版本还低于该功能所需的最低版本门槛。源码里这属于非常前置的集群版本校验：一 … - [快照最大并发操作数配置](https://easysearch.cn/knowledge-base/easysearch_config/snapshot.max_concurrent_operations/): 配置项作用 # snapshot.max_concurrent_operations 配置项用于控制Easysearch 集群中同时进行的快照操作的最大数量。 快照操作包括创建快照、恢复快照、删除快照和克隆快照。此配置限制整个集群的并发快照操作数量，防止资源耗尽。 配置项属性 # 配置路径: snapshot.max_concurrent_operations 数据类型: Integer（整 … - [执行搜索时出错 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/error-while-executing-search-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.8-8.9 1. 错误异常的基本描述 # 执行搜索时出错 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无效的 DiscoveryNode 服务器名称 configuredServerName – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/invalid-discoverynode-server-name-configuredservername-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 无效的 DiscoveryNode 服务器名称 configuredServerName 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判 … - [无法提交操作 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unable-to-submit-operation-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # 无法提交操作 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法解析搜索命中中的 Transform ID - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-search-hit-for-ids-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.2-8.x 1. 错误异常的基本描述 # failed to parse search hit for ids 发生在 Elasticsearch 遍历搜索结果、从内部索引读取 Transform 配置时。源码里会先把命中内容解析成 TransformConfig，再提取 config.getId()；如果 _source 结构不符合 Transform 配置格式，就会在这里失 … - [无法解析监视器条件，比较值必须是标量或 null（Could not parse condition for watch）- 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-condition-for-watch-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.x 1. 错误异常的基本描述 # could not parse condition for watch 是 Elasticsearch Watcher 在解析监视器（Watch）定义时抛出的异常。该异常通常发生在 condition.compare 条件中，当比较运算符后面的比较值不满足类型要求时触发。 结合当前页面已有信息来看， … - [无法识别的选项 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unrecognized-option-expecting-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.16-8.9 1. 错误异常的基本描述 # 无法识别的选项 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [时间戳解析异常 (timestamp_parsing_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/timestamp_parsing_exception/): 为什么这个错误发生 # timestamp_parsing_exception 表示解析时间戳字符串时失败。这通常发生在尝试将字符串转换为日期时间类型时。 这个错误可能由以下原因引起： 格式不匹配：时间戳格式与预期不匹配 无效的日期值：包含无效的日期（如 2 月 30 日） 时区问题：时区信息缺失或错误 格式字符串错误：指定的日期格式字符串不正确 空值或 null：时间戳为空或 null 特殊 … - [索引不存在且自动创建索引设置为false – 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/no-such-index-and-auto-create-index-setting-getkey-is-false-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-6.8 1. 错误异常的基本描述 # 索引不存在且自动创建索引设置为false 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [聚合名称不支持 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/aggregation-name-cannot-support-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.3-7.7 1. 错误异常的基本描述 # Aggregation [name] cannot support regular expression style include/exclude settings as they can only be applied to string fields 是 Elasticsearch 在执行聚合（Aggregation）阶段抛出的异 … - [聚合定义以方括号开头 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/aggregation-definition-for-aggregationname-starts-with-a-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # Aggregation definition for [aggregationName] starts with a [START_OBJECT]; expected a [START_OBJECT] 是 Elasticsearch 在解析聚合（Aggregation）DSL 时抛出的语法异常。该错误表明聚合定义的 JSON 结构不符 … - [脚本缓存过期时间配置](https://easysearch.cn/knowledge-base/easysearch_config/script.cache.expire/): 配置项作用 # script.cache.expire 配置项控制已编译脚本缓存的过期时间。缓存的脚本在指定时间内没有被访问后将被标记为过期，可以被新的编译脚本替换。 配置项类型 # 该配置项为动态配置，可以在运行时通过集群设置 API 进行修改。 默认值 # 0ms（不自动过期） 是否必需 # 可选配置项（有默认值） 取值范围 # 0 ~ 正无穷（0 表示不自动过期） 配置格式 # … - [预期 XContentParser 令牌 VALUE STRING 或 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/expected-xcontentparser-token-value-string-or-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # 预期 XContentParser 令牌 VALUE STRING 或 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 … - [验证快照仓库](https://easysearch.cn/knowledge-base/easysearch_api/verify-snapshot-repository/): 验证指定的快照仓库，检查其配置、存储访问和完整性。 API 格式 # POST /_snapshot/{repository}/_verify API 作用 # 该 API 用于验证快照仓库的健康状态： 验证仓库配置是否正确 检查底层存储系统是否正常工作 确认仓库可以被访问用于快照操作 验证所有仓库设置和参数 API 参数 # 路径参数 # … - [CORS 预检请求缓存时间配置](https://easysearch.cn/knowledge-base/easysearch_config/http.cors.max-age/): 配置项作用 # http.cors.max-age 配置项用于控制CORS 预检请求（Preflight Request）的结果在浏览器中的缓存时间。 当浏览器发送跨域请求前，对于非简单请求（如 PUT、DELETE 或带有自定义头的请求），浏览器会先发送一个 OPTIONS 预检请求。max-age 指定了这个预检响应可以被缓存多长时间。 配置项属性 # 配置路径: … - [GeoJSON 坐标必须是数组——如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/geojson-coordinates-must-be-an-array-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.17-8.9 1. 错误异常的基本描述 # GeoJSON 'coordinates' must be an array 是 Elasticsearch 在解析地理空间数据（GeoJSON）时抛出的异常，表示传入的 coordinates 字段不符合 GeoJSON 规范中"坐标必须是数组"的要求。该错误通常发生在索引文档写入阶段或地理查询解析阶段。 常见现 … - [Grok 模式匹配超时 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/grok-pattern-matching-timed-out-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # Grok 模式匹配超时 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Painless 正则表达式复杂度限制因子配置](https://easysearch.cn/knowledge-base/easysearch_config/script.painless.regex.limit-factor/): 配置项作用 # script.painless.regex.limit-factor 配置项用于控制Painless 脚本中正则表达式的复杂度上限。 这个值表示正则表达式可以处理的字符数是输入字符串长度的多少倍，用于防止过于复杂的正则表达式导致性能问题或内存溢出。 配置项属性 # 配置路径: script.painless.regex.limit-factor 数据类型: Integer（整 … - [Ranges 必须包含对象但遇到了非对象类型——如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/ranges-must-contain-objects-but-hit-a-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Ranges 必须包含对象但遇到了非对象类型— 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Reindex 过程中遇到搜索失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/encountered-search-failures-during-reindex-process-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.5-8.9 1. 错误异常的基本描述 # Reindex 过程中遇到搜索失败 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Terms 查询未指定值 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/no-value-specified-for-terms-query-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Terms 查询未指定值 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Unknown alias name was passed to alias filter - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unknown-alias-name-was-passed-to-alias-filter-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Unknown alias name was passed to alias filter 表示 Elasticsearch 在构建别名过滤器时，使用了不存在的别名名称。 从源码可见，这个异常在 QueryShardContext 的别名过滤器构建路径中抛出，当别名在索引的别名列表中找不到时触发。 典型报错 # … - [主节点选举退避时间配置](https://easysearch.cn/knowledge-base/easysearch_config/cluster.election.back_off_time/): 配置项作用 # cluster.election.back_off_time 配置项控制主节点选举失败后的退避时间增量。每次选举失败后，下一次选举的等待时间会线性增加，增加的幅度由此配置决定。这种退避机制可以避免在集群状态异常时频繁发起选举请求。 配置项类型 # 该配置项为静态配置，需要在启动时设置，修改后需要重启节点才能生效。 默认值 # 100ms 是否必需 # 可选配置项（有默认值） … - [元数据键长度超过20字符错误 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/meta-keys-can-t-be-longer-than-20-chars-but-got-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.6-7.15 1. 错误异常的基本描述 # 元数据键长度超过20字符错误 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [分片快照异常 (index_shard_snapshot_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/index_shard_snapshot_exception/): 为什么这个错误发生 # index_shard_snapshot_exception 是分片快照相关的通用异常，表示在创建或管理分片快照时发生问题。分片快照是创建索引快照的基本单元，每个分片都需要独立完成快照。 这个错误可能由以下原因引起： 分片状态异常：分片处于不允许快照的状态（如关闭、恢复中） 快照正在进行：该分片已经在进行快照操作 分片迁移中：分片正在迁移到其他节点 事务日志问题：无法访 … - [初始化 TrustManagerFactory 失败 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-initialize-a-trustmanagerfactory-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.17 1. 错误异常的基本描述 # 初始化 TrustManagerFactory 失败 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返 … - [字段中文档解析错误 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/error-parsing-document-in-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 字段中文档解析错误 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [快照只能在主分片上执行 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/snapshot-should-be-performed-only-on-primary-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # snapshot should be performed only on primary 表示 Elasticsearch 在执行 shard 快照时发现当前 routing entry 不是 primary，因此立即抛出 IndexShardSnapshotFailedException。源码中这一检查发生在实际 snapshot 逻 … - [找不到主机 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-find-host-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # could not find host [hostname] 表示 Elasticsearch 在将配置中的主机名解析为 IP 地址时失败。该异常通常发生在 DNS 解析或主机名检查阶段，而不是在后续的连接或请求阶段，因此它的本质是地址解析失败，而非连接超时或拒绝连接。 常见现象 # 启动时远程集群（Remote Cluster）或 … - [持久化异步搜索失败结果](https://easysearch.cn/knowledge-base/easysearch_config/async_search.persist_search_failures/): 配置项作用 # async_search.persist_search_failures 配置项控制是否将执行失败的异步搜索结果持久化到系统索引（.async-search）中。默认情况下，只有成功执行的异步搜索结果才会被持久化。 配置项类型 # 该配置项为动态配置，可以在运行时通过集群更新 API 进行修改，无需重启节点。 默认值 # false（不持久化失败结果） 是否必需 # 可选配 … - [按总节点数量恢复配置](https://easysearch.cn/knowledge-base/easysearch_config/gateway.recover_after_nodes/): 配置项作用 # gateway.recover_after_nodes 配置项用于指定集群恢复状态所需要的最少节点总数（包括主节点和数据节点）。 当集群启动时，只有在达到指定数量的节点后，才会开始恢复集群状态。 配置项属性 # 配置路径: gateway.recover_after_nodes 数据类型: integer 默认值: -1（表示禁用此条件） 最小值: -1 是否可选: 是 弃用 … - [无效的聚合排序路径 path - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/invalid-aggregation-order-path-path-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.7-8.9 1. 错误异常的基本描述 # 无效的聚合排序路径 path 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法加载XSD架构文件 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-load-xsd-schema-file-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.7-8.9 1. 错误异常的基本描述 # 无法加载XSD架构文件 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法在带脚本的字段上定义copy_to参数——如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-define-copy-to-parameter-on-a-field-with-a-script-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.13-8.9 1. 错误异常的基本描述 # 无法在带脚本的字段上定义copy_to参数— 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法完成快照删除 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-finalize-snapshot-deletion-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # failed to finalize snapshot deletion 表示 Elasticsearch 已进入快照删除的最终收尾阶段，但在更新分片级快照索引文件、计算残留 blob 或提交新的 shard snapshot 元数据时发生了 IOException，因此抛出 RepositoryException。 它说明删除流程并 … - [无法汇总索引 sourceIndex – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unable-to-rollup-index-sourceindex-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.3-8.9 1. 错误异常的基本描述 # 无法汇总索引 sourceIndex 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [未为multiFieldName属性指定类型 – 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/no-type-specified-for-property-multifieldname-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 未为multiFieldName属性指定类型 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [未找到指定ID的分配——如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/assignment-with-id-not-found-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.17-8.9 1. 错误说明 # assignment with id [xxx] not found 是 Elasticsearch 机器学习模块中出现的异常，完整类名通常为 ResourceNotFoundException。该错误表示在尝试操作（停止、更新、删除或查询）某个机器学习模型分配（Trained Model Assignment）时，集群状态中不存在对应 ID … - [查询待办任务](https://easysearch.cn/knowledge-base/easysearch_api/get-pending-tasks/): 此 API 用于返回集群中待处理任务（Pending Cluster Tasks）的简洁表示。 API # GET /_cat/pending_tasks API 的作用 # 以表格形式显示当前集群中等待执行的集群管理任务信息。这些任务通常是需要在主节点上执行的集群级操作，包括： 任务插入顺序：任务在队列中的位置 等待时间：任务在队列中等待的时间 任务优先级：任务的执行优先级 任务来源：任务 … - [没有可用分片 (no_shard_available_action_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/no_shard_available_action_exception/): 为什么这个错误发生 # no_shard_available_action_exception 表示操作无法找到可用的分片来执行。 如何修复 # 1. 检查分片状态 # GET /_cat/shards?v 2. 解释未分配原因 # GET /_cluster/allocation/explain 3. 启用分片分配 # PUT /_cluster/settings { … - [磁盘分配决策包含重定位分片配置](https://easysearch.cn/knowledge-base/easysearch_config/cluster.routing.allocation.disk.include_relocations/): 配置项作用 # cluster.routing.allocation.disk.include_relocations 配置项用于控制在计算节点磁盘使用量时，是否将正在迁移到该节点的分片大小计入磁盘使用量。 配置项属性 # 配置路径: cluster.routing.allocation.disk.include_relocations 数据类型: boolean 默认值: true 是否可 … - [自定义元数据字段不包含有效的 long 类型实际值 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/custom-metadata-field-does-not-contain-a-valid-long-actual-value-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # 自定义元数据字段不包含有效的 long 类型实际值 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能 … - [解析通配符服务失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-wildcard-service-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.7-8.9 1. 错误异常的基本描述 # 解析通配符服务失败 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [aborted on initialization - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/aborted-on-initialization-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.8-7.17 1. 错误异常的基本描述 # aborted on initialization 是 Elasticsearch 在执行快照过程中抛出的异常。当快照任务在初始化阶段失败时，Elasticsearch 会中止该快照并将其标记为失败。这通常发生在快照刚开始执行时，遇到了无法恢复的问题，如仓库不可用、主节点变更、分片分配失败等。 常见现象 # … - [allocation for model with id not found - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/allocation-for-model-with-id-not-found-how-to-solve-this-elasticsearch-exception/): 适用版本： 8+ 1. 错误异常的基本描述 # allocation for model with id [model_id] not found 是 Elasticsearch 在管理**机器学习模型分配（Trained Model Allocation）**时抛出的资源未找到错误。当你尝试停止、更新或查询某个机器学习模型的分配状态，但该模型 ID 在集群状态中不存在时，就会触发此错误。这可 … - [AUTO CREATE INDEX SETTING getKey – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/auto-create-index-setting-getkey-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.x – 8.x 1. 错误异常的基本描述 # AUTO_CREATE_INDEX_SETTING getKey 异常在 Elasticsearch 尝试自动创建索引、但 action.auto_create_index 配置禁止该行为时触发。该异常的核心含义是：请求的目标索引不存在，而集群的自动创建索引策略又不允许为该索引（或该模式匹配的索引）执行自动创建， … - [cannot delete model as it is currently deployed - 无法删除已部署的模型如何解决](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-delete-model-as-it-is-currently-deployed-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.0-8.x 1. 错误异常的基本描述 # Cannot delete model [model_id] as it is currently deployed 表示在 Elasticsearch 中删除训练模型（Trained Model）时，该模型仍处于已部署状态，被分配到了某个节点上运行。为防止在线推理服务中断，Elasticsearch 会阻止删除当前仍被分配和运行的模 … - [ElasticsearchException – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/elasticsearchexception-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.6-8.1 1. 错误异常的基本描述 # ElasticsearchException 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [failed to load settings from - 从文件路径加载设置失败](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-load-settings-from-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Failed to load settings from 出现在 Settings.Builder 的文件加载路径。日志上下文显示，代码会先把内容写入 ByteArrayInputStream，再调用 output.loadFromStream(configFile.getFileName().toString(), is, … - [XContent 解析器期望 START_OBJECT 标记 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/expected-xcontentparser-token-start-object-in-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # XContent 解析器期望 START_OBJECT 标记 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接 … - [什么是“自主可控搜索引擎”？核心能力解读](https://easysearch.cn/knowledge-base/insight/what-is-an-autonomous-and-controllable-search-engine-core-capabilities-explained/): 引言：国产化浪潮下的必然选择 # 随着国际技术竞争加剧和信创政策落地（2026 年起政府采购对本国产品设 20% 价格优惠，2027 年关键行业核心系统国产化率目标 70%），“自主可控”成为企业 IT 选型的核心诉求。搜索引擎作为处理海量数据的基础软件，其国产化替代迫在眉睫。极限科技（INFINI Labs）推出的 INFINI Easysearch，正是为国产化环境量身定制的轻量级分布式搜索 … - [仓库缺少 location 配置 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/missing-location-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.x 1. 错误异常的基本描述 # missing location 发生在文件系统类型的快照仓库初始化阶段。根据保留代码，Elasticsearch 期望仓库配置里有 location，并且这个位置应该是所有 master 和 data 节点都能访问的共享路径；如果没配，就会抛出 RepositoryException。 常见现象 # 创建 fs … - [分析失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-analyze-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 分析失败 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返回 400、404、409、429、500 … - [发布时失败——如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/publishing-failed-while-starting-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.9-8.9 1. 错误异常的基本描述 # 发布时失败— 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返回 400、404、409、429、500 … - [字段发现未知 shape - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/field-fieldname-found-and-unknown-shape-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8 1. 错误异常的基本描述 # Field [fieldName] found and unknown shape 表示目标字段存在，但传入的几何对象既不是当前实现支持的标准 shape，也不是可识别的 shape 数组集合。根据源码，这个异常出现在 geo 查询构建阶段，说明请求中的 queryShape 结构无法被解释成合法几何体。 常见现象 # geo_shape … - [字段名后出现意外的标记](https://easysearch.cn/knowledge-base/elasticsearch_error/unexpected-token-token-after-fieldname-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 字段名后出现意外的标记 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [尝试删除多个不存在的快照 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/attempting-to-remove-non-existent-snapshots-from-repository-data-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.8-8.9 1. 错误异常的基本描述 # Attempting to remove non-existent snapshots {} from repository data 表示 Elasticsearch 正在批量从 RepositoryData 删除多个 snapshot，但请求中至少有一部分 snapshot 并不在当前仓库元数据里。根据当前源码，系统会先过滤掉目标集 … - [并发快照执行异常 (concurrent_snapshot_execution_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/concurrent_snapshot_execution_exception/): 为什么这个错误发生 # concurrent_snapshot_execution_exception 表示尝试同时执行多个冲突的快照或恢复操作。快照操作对某些资源（如索引、分片、仓库）是独占的，不能同时执行。 这个错误可能由以下原因引起： 同一索引多次快照：同时对同一索引执行多个快照 快照和恢复冲突：同时进行快照和恢复操作 同名快照：尝试创建同名的快照 仓库操作冲突：同一仓库的多个并发快照操 … - [底层取消机制配置](https://easysearch.cn/knowledge-base/easysearch_config/search.low_level_cancellation/): 配置项作用 # search.low_level_cancellation 配置项控制是否启用搜索任务的底层取消机制。启用后，搜索任务可以更及时地响应取消请求，但可能会带来一些性能开销。 配置项类型 # 该配置项为动态配置，可以在运行时通过集群设置 API 进行修改。 默认值 # true（启用底层取消） 是否必需 # 可选配置项（有默认值） 取值范围 # true - … - [恢复暂停失败 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-pause-recovery-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 恢复暂停失败 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返回 400、404、409、429、500 … - [排序 + 搜索一起用，Easysearch 性能会怎样变化](https://easysearch.cn/knowledge-base/perf/sorting-and-searching-together-performance-impact/): 一、Easysearch 排序（sort）核心原理 # Easysearch 的排序机制基于 Lucene 底层实现，针对分布式场景和时序数据特点做了深度优化，核心为两阶段高效执行流程，无中间结果冗余存储： 检索阶段：通过倒排索引完成关键词匹配，筛选符合条件的文档集合，生成初步结果集（默认按相关性得分_score排序）；分片仅返回文档 ID 和排序字段值（而非完整文档），协调节点无需存储冗余中 … - [操作系统监控刷新间隔配置](https://easysearch.cn/knowledge-base/easysearch_config/monitor.os.refresh_interval/): 配置项作用 # monitor.os.refresh_interval 配置项用于控制操作系统监控服务收集和刷新操作系统统计信息的间隔时间。 此配置决定了 OsService 多久刷新一次系统级别指标，包括 CPU 使用率、内存使用、系统负载、交换空间等。 配置项属性 # 配置路径: monitor.os.refresh_interval 数据类型: TimeValue（时间值） 默认值: … - [故障检测Ping重试次数配置](https://easysearch.cn/knowledge-base/easysearch_config/discovery.zen.fd.ping_retries/): 配置项作用 # discovery.zen.fd.ping_retries 配置项用于控制故障检测机制中 ping 失败后的重试次数。 只有当连续 ping 失败次数达到此配置值时，节点才会被判定为故障。 配置项属性 # 配置路径: discovery.zen.fd.ping_retries 数据类型: integer 默认值: 3 是否可选: 是 弃用状态: ⚠️ 已弃用 配置项详解 # … - [文件系统健康检查间隔配置](https://easysearch.cn/knowledge-base/easysearch_config/monitor.fs.health.refresh_interval/): 配置项作用 # monitor.fs.health.refresh_interval 配置项用于控制文件系统健康检查的刷新间隔时间。 FsHealthService 会按照此间隔定期检查文件系统的健康状况，通过在每个数据路径上创建临时文件来验证文件系统的写入能力。 配置项属性 # 配置路径: monitor.fs.health.refresh_interval 数据类型: … - [无法解析电子邮件模板：存在空字段 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-email-template-empty-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 这个异常出现在解析邮件模板对象时。Watcher 期望在模板对象里读到明确的字段名，比如 text 或 html；如果解析到一个值时，当前没有对应字段名，就会抛出 empty field。 常见触发情形是对象结构损坏，例如模板渲染后生成了非法 JSON，导致解析器进入对象后拿到值，却没有前置字段名。 2. 为什么会发生这个错误 # 附 … - [无法解析角色限制 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-restriction-for-role-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.9-8.9 1. 错误异常的基本描述 # 无法解析角色限制 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [日期字段必须设置 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/must-be-set-for-date-fields-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 日期字段必须设置 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [期望的分片平衡分配器未使用，未找到期望的平衡配置 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/desired-balance-allocator-is-not-in-use-no-desired-balance-found-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.6-8.9 1. 错误异常的基本描述 # 期望的分片平衡分配器未使用，未找到期望的平衡配置 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [查询主节点](https://easysearch.cn/knowledge-base/easysearch_api/get-master-node/): 此 API 用于返回 Easysearch 集群主节点（Master Node）的详细信息。 API # GET /_cat/master API 的作用 # 显示当前集群中主节点的详细信息，包括： 节点 ID：主节点的唯一标识符 主机名：主节点所在的主机名 IP 地址：主节点的 IP 地址 节点名称：主节点的名称 主节点负责管理集群范围的操作，如创建索引、分配分片、维护集群状态等。当没有 … - [桶数量过多 (too_many_buckets_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/too_many_buckets_exception/): 为什么这个错误发生 # too_many_buckets_exception 表示聚合操作产生的桶（bucket）数量超过了集群配置的限制。默认限制为 65535。 这个错误可能由以下原因引起： 高基数聚合：对高基数字段进行 terms 聚合 数据量大：文档数量多且字段值唯一 深度嵌套聚合：多层嵌套聚合产生大量组合 interval 过小：date_histogram 聚合使用过小的时间间隔 … - [父字段映射必须包含 type 选项——如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/parent-field-mapping-must-contain-the-type-option-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-6.8 1. 错误异常的基本描述 # 父字段映射必须包含 type 选项— 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [等待推理结果超时 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/timeout-waiting-for-inference-result-how-to-solve-this-elasticsearch-exception/): 适用版本： 8-8.9 1. 错误异常的基本描述 # 等待推理结果超时 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返回 400、404、409、429、500 … - [等待映射更新超时 – 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/timed-out-waiting-for-mapping-updates-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # 等待映射更新超时 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [索引状态管理模板迁移控制配置](https://easysearch.cn/knowledge-base/easysearch_config/index_state_management.template_migration.control/): 配置项作用 # index_state_management.template_migration.control 配置项用于控制索引状态管理（ISM）模板迁移的行为和时间戳。 配置项属性 # 配置路径: index_state_management.template_migration.control 数据类型: Long（长整数） 默认值: 0L 最小值: -2L 是否可选: 是 作用 … - [脚本允许上下文配置](https://easysearch.cn/knowledge-base/easysearch_config/script.allowed_contexts/): 配置项作用 # script.allowed_contexts 配置项控制允许执行脚本的上下文环境。脚本上下文定义了脚本可以运行的位置（如聚合、搜索、更新等）。 是否可选 # 是 默认值 # [] (空列表，允许所有上下文) 配置项类型 # 动态配置 - 可以在运行时修改 配置格式 # # 允许所有上下文（默认） script.allowed_contexts: [] # 只允许特定上下 … - [自定义脚本排序类型不支持 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/custom-script-sort-type-type-not-supported-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # 自定义脚本排序类型不支持 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [范围查询 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/range-query-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.3-8.9 1. 错误异常的基本描述 # 范围查询 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返回 400、404、409、429、500 … - [another snapshot is currently running cannot delete - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/another-snapshot-is-currently-running-cannot-delete-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.7+ 1. 错误异常的基本描述 # another snapshot is currently running cannot delete 是 Elasticsearch 在删除快照时抛出的并发控制错误。当你尝试删除某个快照（DELETE /_snapshot/<repo>/<snapshot>），但同一仓库中还有其他快照任务正在执行时，就会触发 … - [can't round a bytes - 无法对 BYTES 类型执行 rounding 如何解决](https://easysearch.cn/knowledge-base/elasticsearch_error/can-t-round-a-bytes-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.9-8.x 1. 错误异常的基本描述 # can't round a [BYTES] 表示 Elasticsearch 正试图对一个 BYTES 类型字段执行 rounding（取整/分桶）逻辑，例如在某些需要离散化、分桶或区间归整的聚合准备阶段；但 BYTES 字段不支持这种数值 rounding 操作，因此抛出异常。 常见现象 # 聚合请求在执行前或执行初期失败， … - [could not parse time value expected either a string or a null value but found - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-time-value-expected-either-a-string-or-a-null-value-but-found-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # could not parse time value. expected either a string or a null value but found [token] instead 是 Elasticsearch 在解析 TimeValue（时间值）时抛出的异常。此错误表示当前解析路径只接受字符串或 null， … - [Easysearch 查询性能优化：为什么Filter缓存能让搜索飞起来？](https://easysearch.cn/knowledge-base/perf/easysearch-query-performance-why-filter-cache-makes-search-faster/): 在使用 INFINI Easysearch 开发应用时，你是否遇到过这样的疑惑： “为什么加上了时间范围限制，查询反而变慢了？” “同样的查询，为什么第二次执行比第一次快那么多？” “在高并发场景下，CPU 占用率居高不下？” 很多时候，这些问题的答案都指向同一个优化点：合理使用 Filter Context（过滤上下文）。 在 Easysearch 中，并不是所有的搜索都需要计算相关性评 … - [Generic 线程池保活时间配置](https://easysearch.cn/knowledge-base/easysearch_config/thread_pool.generic.keep_alive/): 配置项作用 # thread_pool.generic.keep_alive 配置项用于控制通用线程池中弹性线程的保活时间。 当线程数超过核心线程数时，空闲的弹性线程在指定时间后会被回收。 配置项属性 # 配置路径: thread_pool.generic.keep_alive 数据类型: TimeValue（时间值） 默认值: 30s（30 秒） 是否可选: 是 作用域: … - [GeoJSON坐标必须至少包含两个值 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/geojson-coordinates-must-contain-at-least-two-values-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.2-8.2 1. 错误异常的基本描述 # GeoJSON坐标必须至少包含两个值 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [NAME 查询不支持 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/name-query-does-not-support-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # NAME 查询不支持 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Transient 临时设置类别](https://easysearch.cn/knowledge-base/easysearch_config/transient/): 配置项作用 # transient 不是单独的配置项，而是 Easysearch 中临时设置类别，用于定义仅在当前会话期间生效、集群重启后丢失的配置。 配置项属性 # 配置路径: N/A（这是一个类别，不是具体配置项） 数据类型: N/A（包含多种类型的设置） 默认值: N/A 作用域: 可变（取决于具体设置，可以是 NodeScope、IndexScope 等） 动态更新: 是（临时设置本 … - [Unknown field name [field] - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unknown-field-name-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.9 1. 错误异常的基本描述 # unknown field name [field] 表示 Elasticsearch 在解析快照相关元数据（如 SnapshotInfo、RepositoryMeta、IndexMeta）时，遇到了无法识别的字段名。该异常属于 ElasticsearchParseException，通常出现在快照恢复、仓库加载或跨集群数据迁移场景中。 … - [Unknown key for a token in [currentFieldName] - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unknown-key-for-a-token-in-currentfieldname-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # unknown key for a token in [currentFieldName] 表示 Elasticsearch 在解析某个配置对象时，发现当前字段后面跟着一个不被该解析器接受的 token 类型，因此无法把它识别成合法参数。 从当前页面保留的源码来看，异常本质是 字段后的值类型或 JSON 结构不符合预期。它并不一定只出 … - [主节点处理过时的分片启动事件导致分片失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/master-processed-stale-shard-started-event-failing-shard-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.17-8.9 1. 错误异常的基本描述 # 主节点处理过时的分片启动事件导致分片失败 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [事务日志持久性配置](https://easysearch.cn/knowledge-base/easysearch_config/config_index.translog.durability/): 配置项作用 # index.translog.durability 配置项控制事务日志（Translog）的持久化策略。事务日志用于在崩溃恢复时防止数据丢失，此配置决定何时将事务日志写入磁盘。 配置项类型 # 该配置项为动态配置，可以在运行时通过索引设置 API 进行修改。 默认值 # request（每个请求后 fsync） 是否必需 # 可选配置项（有默认值） 可选值 # 值 … - [停止节点失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-stop-node-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.8 1. 错误异常的基本描述 # 停止节点失败 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [全局可组合模板不能指定设置——如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/global-composable-templates-may-not-specify-the-setting-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # 全局可组合模板不能指定设置— 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [冻结索引请求未被确认 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/freeze-index-request-failed-to-be-acknowledged-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.6-7.17 1. 错误异常的基本描述 # 冻结索引请求未被确认 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [在目录文件中未找到segments文件 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/no-segments-file-found-in-directory-files-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.1-8.9 1. 错误异常的基本描述 # 在目录文件中未找到segments文件 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [字段权限的异常必须是已授权字段的子集 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/exceptions-for-field-permissions-must-be-a-subset-of-the-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # 字段权限的异常必须是已授权字段的子集 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [对象映射器 fullPath 被多次定义 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/object-mapper-mapper-fullpath-is-defined-more-than-once-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.1-8.9 1. 错误异常的基本描述 # 对象映射器 fullPath 被多次定义 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [并发映射更新数量配置](https://easysearch.cn/knowledge-base/easysearch_config/indices.mapping.max_in_flight_updates/): 配置项作用 # indices.mapping.max_in_flight_updates 配置项控制允许同时进行的动态映射更新的最大数量。当有多个新字段需要添加到索引时，此配置限制并发更新的数量，避免过度的集群状态更新。 配置项类型 # 该配置项为动态配置，可以在运行时通过集群设置 API 进行修改。 默认值 # 10 是否必需 # 可选配置项（有默认值） 取值范围 # 1 ~ … - [故障检测Ping超时配置](https://easysearch.cn/knowledge-base/easysearch_config/discovery.zen.fd.ping_timeout/): 配置项作用 # discovery.zen.fd.ping_timeout 配置项用于控制故障检测机制中单次 ping 请求的超时时间。 当节点向其他节点发送 ping 请求时，如果在此时间内未收到响应，则视为该次 ping 失败。 配置项属性 # 配置路径: discovery.zen.fd.ping_timeout 数据类型: TimeValue（时间值） 默认值: 30s（30秒） 是 … - [数据流请求 getName 不存在 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/data-stream-request-getname-does-not-exist-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.11-8.11 1. 错误异常的基本描述 # 数据流请求 getName 不存在 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法解析监视器条件，未知比较运算符（Could not parse condition for watch. unknown comparison operator）- 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-condition-for-watch-unknown-comparison-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.x 1. 错误异常的基本描述 # could not parse [compare] condition for watch [...]. unknown comparison operator [...] 表示 Elasticsearch Watcher 在解析 compare 条件时，遇到了一个无法识别的比较运算符字段名。 Watcher 的 compare 条件用 … - [未分类执行异常 (uncategorized_execution_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/uncategorized_execution_exception/): 为什么这个错误发生 # uncategorized_execution_exception 表示执行过程中发生未分类的错误。这是一个通用的执行异常，通常用于包装无法归类到特定类型的错误。 这个错误可能由以下原因引起： 未预期的错误：发生了未预期的错误类型 包装异常：包装了其他类型的异常 异步执行失败：异步任务执行失败 并发操作问题：并发操作导致的未预期错误 资源限制：达到某种资源限制 内部错 … - [构建 Scroll 请求体失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-build-scroll-entity-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # failed to build scroll entity 表示 Elasticsearch 客户端在构建 Scroll 请求的 JSON 请求体阶段发生了序列化失败。与大多数网络层面的异常不同，这个错误发生在请求尚未发出之前——即在本地构造 scroll_id 对应的 JSON 实体时，XContentBuilder 在写入或字符串化 … - [查询快照（Cat格式）](https://easysearch.cn/knowledge-base/easysearch_api/get-snapshot-cat-format/): 以紧凑的表格形式返回快照信息。 API 格式 # GET /_cat/snapshots GET /_cat/snapshots/{repository} API 作用 # 该 API 以表格形式返回快照信息： 显示所有仓库或指定仓库的快照 显示快照状态、时间、分片统计等信息 快速查看快照健康状态 API 参数 # 路径参数 # … - [等待映射更新时集群服务被关闭 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cluster-service-was-closed-while-waiting-for-mapping-updates-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.16-8.9 1. 错误异常的基本描述 # 等待映射更新时集群服务被关闭 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [节点端口文件配置](https://easysearch.cn/knowledge-base/easysearch_config/node.portsfile/): 配置项作用 # node.portsfile 配置项用于控制是否将节点实际绑定的端口信息写入文件。 启用后，节点会在日志目录中创建两个端口文件： transport.ports - 包含传输层服务的端口（通常为 9300） http.ports - 包含 HTTP 服务的端口（通常为 9200） 主要用于测试环境和外部工具集成，方便动态检测节点实际使用的端口。 配置项属性 # 配置路径: … - [设置异常 (settings_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/settings_exception/): 为什么这个错误发生 # settings_exception 表示在处理集群、节点或索引设置时发生错误。这个错误通常与配置参数的有效性或兼容性有关。 这个错误可能由以下原因引起： 设置名称拼写错误：配置参数名称不正确 设置值格式错误：配置值的数据类型或格式不符合要求 不允许动态修改：尝试动态修改需要重启节点的静态设置 设置值超出范围：数值超出允许的最小/最大值 冲突的设置： … - [路径nestedPath下的嵌套对象不是嵌套类型 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/nested-nested-object-under-path-nestedpath-is-not-of-nested-type-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # 路径nestedPath下的嵌套对象不是嵌套类型 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返 … - [遇到无法自动重试的失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/experienced-failure-that-cannot-be-automatically-retried-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.7-7.9 1. 错误异常的基本描述 # 遇到无法自动重试的失败 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [重写失败 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/rewrite-failed-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.16-8.9 1. 错误异常的基本描述 # 重写失败 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [预期 currentFieldName 为数组 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/expected-array-for-currentfieldname-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.17 1. 错误异常的基本描述 # 预期 currentFieldName 为数组 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [预期 END_OBJECT 但得到 parser.currentToken - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/expected-end-object-but-got-parser-currenttoken-how-to-solve-this-elasticsearch-exception/): 适用版本： 7-8.9 1. 错误异常的基本描述 # 预期 END_OBJECT 但得到 parser.currentToken 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Both a secret as well as a shared access token were set - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/both-a-secret-as-well-as-a-shared-access-token-were-set-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 这条异常表示 Azure 仓库客户端的认证方式配置冲突。源码要求 secret key 和 shared access token 二选一，若两者同时存在，就会抛出 SettingsException。 常见现象 # Azure 仓库在初始化时失败。 看起来认证信息“都配了”，但实际因为冲突无法使用。 … - [Common analyzer analyzer 未找到——如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/common-analyzer-analyzer-not-found-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.17 1. 错误异常的基本描述 # Common analyzer analyzer 未找到— 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Easysearch 性能优化，没有银弹，只有取舍](https://easysearch.cn/knowledge-base/perf/easysearch-performance-optimization-tradeoffs-not-silver-bullets/): 在 Easysearch 的技术交流群里，经常会看到这样的提问： “大佬，有没有生产环境的配置文件发一份？” “我的查询慢了，调哪个参数能变快？” 遗憾的是，这些问题没有标准答案。性能优化从来没有“银弹”（Silver Bullet），只有在不同约束条件下的“取舍”（Trade-offs）。 如果你试图在一个配置中同时追求极致的写入速度、毫秒级的查询响应和最低的硬件成本，你违背了分布式系统的物 … - [failed to load metadata - 元数据加载失败](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-load-metadata-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # failed to load metadata 来自节点级元数据收集流程。日志上下文显示，代码在构造 NodeSnapshotStatus 时捕获了通用异常并抛出当前错误，这说明问题通常与快照、仓库或本地元数据读取有关，而不是普通网络请求失败。 这不是泛化的"节点通信失败"，而是快照/仓库元数据读取失败，通常发生在查 … - [Listener 线程池大小配置](https://easysearch.cn/knowledge-base/easysearch_config/thread_pool.listener.size/): 配置项作用 # thread_pool.listener.size 配置项用于控制监听器线程池的线程数量。 配置项属性 # 配置路径: thread_pool.listener.size 数据类型: Integer（整数） 默认值: (CPU核心数 + 1) / 2，最大不超过 10 是否可选: 是 作用域: NodeScope（节点级别） 动态更新: 是（可以动态更新，无需重启） 废弃状 … - [Meta 必须是一个对象却得到了 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/meta-must-be-an-object-got-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.6-7.15 1. 错误异常的基本描述 # Meta 必须是一个对象却得到了 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [UUID长度不能大于事务日志——如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/uuid-length-can-t-be-larger-than-the-translog-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # UUID长度不能大于事务日志— 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [下载过程中的错误 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/error-during-downloading-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.13-8.9 1. 错误异常的基本描述 # 下载过程中的错误 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [不允许创建快照 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/snapshot-is-not-allowed-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # snapshot is not allowed 表示 Elasticsearch 在为某个 shard 获取快照所需的 IndexCommit 时，发现当前 IndexShardState 不满足要求，因此直接抛出 IllegalIndexShardStateException。从源码看，只有 STARTED 或 CLOSED 状态允许 … - [不再是主节点 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/no-longer-master-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.7-8.9 1. 错误异常的基本描述 # 不再是主节点 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [不支持 DISTINCT 但却被指定 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/does-not-support-distinct-yet-it-was-specified-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.12-8.9 1. 错误异常的基本描述 # 不支持 DISTINCT 但却被指定 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [传输异常 (transport_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/transport_exception/): 为什么这个错误发生 # transport_exception 是节点间通信传输过程中发生的通用异常。Easysearch 使用传输层（Transport）进行节点间通信，当通信失败时会抛出此异常。 这个错误可能由以下原因引起： 网络问题：节点间网络连接中断或延迟过高 节点宕机：目标节点宕机或无响应 连接超时：连接请求超时 端口被占用：通信端口（9300）被其他进程占用 防火墙阻断：防火墙规则 … - [分片恢复活动超时配置](https://easysearch.cn/knowledge-base/easysearch_config/indices.recovery.recovery_activity_timeout/): 配置项作用 # indices.recovery.recovery_activity_timeout 配置项控制分片恢复过程中允许无活动的最大时间间隔。如果在指定时间内没有检测到任何恢复活动（数据传输、文件操作等），恢复操作将被标记为失败。 配置项类型 # 该配置项为动态配置，可以在运行时通过集群设置 API 进行修改。 默认值 # 30m（ … - [在指定偏移处期望十六进制字符但发现了其他字符 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/expected-hexadecimal-at-offset-found-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 在指定偏移处期望十六进制字符但发现了其他字符 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [多值字段词向量高亮模式配置](https://easysearch.cn/knowledge-base/easysearch_config/search.highlight.term_vector_multi_value/): 配置项作用 # search.highlight.term_vector_multi_value 配置项用于控制多值字段的离散高亮处理模式。 当设置为 true（默认值）时，启用离散多值高亮模式，将每个值独立处理；当设置为 false 时，将所有值合并为一个连续的字符串进行处理。 配置项属性 # 配置路径: search.highlight.term_vector_multi_value 数 … - [字段fieldName上声明的类型type没有处理器 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/no-handler-for-type-type-declared-on-field-fieldname-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 字段fieldName上声明的类型type没有处理器 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能 … - [字段类型错误但仅支持数值类型——如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/field-is-of-type-but-only-numeric-types-are-supported-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # 字段类型错误但仅支持数值类型— 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [快照仓库路径配置](https://easysearch.cn/knowledge-base/easysearch_config/path.repo/): 配置项作用 # path.repo 配置项指定共享文件系统仓库的位置，用于存储快照数据。 是否可选 # 是 默认值 # [] (空列表) 配置项类型 # 静态配置 - 需要重启节点才能生效 配置格式 # # 单个仓库路径 path.repo: - /backup/easysearch # 多个仓库路径 path.repo: - /backup/easysearch - … - [恢复时无法修改设置k - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-modify-setting-k-on-restore-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # cannot modify setting [k] on restore 表示你在执行快照恢复时，通过 index_settings 或类似参数试图覆盖某个被 Elasticsearch 列为不可修改的索引设置。源码中会先过滤恢复请求里的 setting 变更项，只要命中 UNMODIFIABLE_SETTINGS， … - [搜索异常 (search_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/search_exception/): 为什么这个错误发生 # search_exception 是搜索操作过程中发生的通用异常。这个错误表示在执行搜索查询时遇到了问题。 这个错误可能由以下原因引起： 查询语法错误：查询 DSL 语法不正确或格式错误 字段不存在：查询中引用的字段在索引映射中不存在 数据类型不匹配：查询类型与字段数据类型不兼容 索引损坏：索引或分片损坏导致搜索失败 分片不可用：目标分片未分配或不可用 内存不足：搜索操 … - [无效的电子邮件地址 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/invalid-email-address-how-to-solve-this-elasticsearch-exception/): 适用版本： 7-8.9 1. 错误异常的基本描述 # Watcher 在解析邮件 action 时，会先把 to、cc、bcc 等字段中的地址列表转换为 Email.Address 对象，然后逐个执行 validate()。只要其中任意一个地址格式不合法，就会抛出当前异常。 典型报错： invalid email address [ops.example.com] 常见非法值包括： 缺少 @ … - [无法更新汇总索引 rollupIndexName 的设置 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unable-to-update-settings-of-rollup-index-rollupindexname-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # 无法更新汇总索引 rollupIndexName 的设置 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能 … - [无法生成 KEK 来包装 DEK dekId - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failure-to-generate-kek-to-wrap-the-dek-dekid-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.12-8.6 1. 错误异常的基本描述 # Failure to generate KEK to wrap the DEK [dekId] 表示 Elasticsearch 在加密仓库流程中，尝试根据仓库密码派生 KEK 时失败，因此后续无法继续包装 DEK。 从日志片段可以看出，异常发生在 AESKeyUtils.generatePasswordBasedKey 这一步，还没 … - [无法解析 Watch，缺少必需字段 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-watch-missing-required-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.x 1. 错误异常的基本描述 # could not parse watch [<id>]. missing required field [trigger] 表示 Elasticsearch 在解析 Watch 定义时，发现顶层缺少必需字段。根据日志上下文，这里的必需字段就是 trigger。 这不是运行期执行失败，而是 Watch 定义在解析阶段就不合 … - [无法连接到空节点 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/can-t-connect-to-a-null-node-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 无法连接到空节点 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [未知的运算符 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unknown-operator-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 未知的运算符 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [查询分片](https://easysearch.cn/knowledge-base/easysearch_api/get-shard/): 此 API 用于显示集群中所有索引的分片状态和详细统计信息。 API # GET /_cat/shards GET /_cat/shards/{index} API 的作用 # 返回集群中所有分片的状态和统计信息，包括： 分片基本信息：索引名称、分片 ID、主副分片标识、状态 文档统计：分片中的文档数量 存储信息：分片存储大小 节点信息：分片所在节点的 IP 和名称 操作统计：索引、查询、刷 … - [父 ID 不匹配文档值 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/parent-id-mismatch-document-value-is-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-6.8 1. 错误异常的基本描述 # 父 ID 不匹配文档值 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [经度值非法 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/illegal-longitude-value-for-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # 经度值非法 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [缺少必填字段 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/missing-required-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # 缺少必填字段 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [缺少必需的字段选项 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/the-required-field-option-is-missing-how-to-solve-this-elasticsearch-exception/): 适用版本： 7-8.9 1. 错误异常的基本描述 # 缺少必需的字段选项 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [自动创建索引配置](https://easysearch.cn/knowledge-base/easysearch_config/action.auto_create_index/): 配置项作用 # action.auto_create_index 配置项控制当用户向不存在的索引执行写入操作（如索引文档、更新文档等）时，Easysearch 是否自动创建该索引。 配置项类型 # 该配置项为动态配置，可以在运行时通过集群更新 API 进行修改，无需重启节点。 配置值格式 # 该配置项支持以下三种格式： 布尔值 true：自动创建所有索引（默认值） false：禁止自动 … - [请求断路器开销系数配置](https://easysearch.cn/knowledge-base/easysearch_config/indices.breaker.request.overhead/): 配置项作用 # indices.breaker.request.overhead 配置项控制请求断路器的内存开销估算常数。 默认值 # 1.0 配置类型 # 动态配置 配置格式 # # 默认配置 indices.breaker.request.overhead: 1.0 - [邮件账户设置中的默认邮件值无效 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/invalid-email-defaults-in-email-account-settings-accountname-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Watcher 的 email account 支持配置默认值，例如默认 to、cc、bcc、subject。Elasticsearch 在加载这些默认配置时，会先把默认地址解析成地址列表；只要 defaults 中有不合法值，就会在账户初始化阶段抛出当前异常。 这类错误通常不是某一个 watch 的局部问题，而是整个 email … - [HTTP CORS 允许源配置](https://easysearch.cn/knowledge-base/easysearch_config/http.cors.allow-origin/): 配置项作用 # http.cors.allow-origin 配置项指定允许通过跨域资源共享 (CORS) 访问 Easysearch 的源列表。 是否可选 # 是 默认值 # "" (空字符串，禁用 CORS) 配置项类型 # 静态配置 - 需要重启节点才能生效 配置格式 # # 禁用 CORS（默认） http.cors.allow-origin: … - [http request 缺少必填字段 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-http-request-missing-required-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # could not parse http request. missing required [field] field 是 Elasticsearch Watcher 组件在解析 HTTP 请求配置时抛出的异常。当 Watcher 尝试构建一个 HTTP 请求动作（webhook、HTTP input 等），但在解析配置后发现某些必 … - [IN 查询暂不支持 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/in-query-not-supported-yet-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # IN 查询暂不支持 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Incoming term applyCommit getTerm does not match last accepted term – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/incoming-term-applycommit-getterm-does-not-match-last-accepted-term-how-to-solve-this-elasticsearch-exception/): 适用版本： 7-7.15 1. 错误异常的基本描述 # Incoming term applyCommit getTerm does not match last accepted term 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面 … - [Name字段类型错误——如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/name-field-which-is-of-type-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.1-7.15 1. 错误异常的基本描述 # Name字段类型错误— 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Transport TCP 保活配置](https://easysearch.cn/knowledge-base/easysearch_config/transport.tcp.keep_alive/): 配置项作用 # transport.tcp.keep_alive 配置项用于控制是否启用 TCP Keep-Alive 机制。 配置项属性 # 配置路径: transport.tcp.keep_alive 数据类型: Boolean（布尔值） 默认值: true 是否可选: 是 作用域: NodeScope（节点级别） 动态更新: 否（需要重启节点生效） 配置建议 # 默认配置 # … - [version字段不可搜索——如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/the-version-field-is-not-searchable-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # version字段不可搜索— 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Watcher报告：轮询等待时线程被中断](https://easysearch.cn/knowledge-base/elasticsearch_error/watch-reporting-thread-was-interrupted-while-waiting-for-polling-aborting-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # Watcher报告：轮询等待时线程被中断 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [从事务日志读取后无法重新应用过滤器 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-reapply-filters-for-id-after-reading-from-translog-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.6-7.14 1. 错误异常的基本描述 # 从事务日志读取后无法重新应用过滤器 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [传输层 TCP 端口配置](https://easysearch.cn/knowledge-base/easysearch_config/transport.tcp.port/): 配置项作用 # transport.tcp.port 配置项控制集群节点间通信使用的 TCP 端口范围。传输层用于节点之间的内部通信，包括集群状态同步、分片数据传输等。 配置项类型 # 该配置项为静态配置，需要在启动时设置，修改后需要重启节点才能生效。 默认值 # 9300-9400 是否必需 # 可选配置项（有默认值） 取值范围 # 单端口或端口范围（如 9300 … - [内存、磁盘、缓存：Easysearch 性能优化的三重奏](https://easysearch.cn/knowledge-base/perf/easysearch-memory-disk-cache-performance-optimization/): 在搜索引擎的性能调优中，我们常常陷入一个误区：盲目堆砌硬件。加内存、换更快的 SSD、堆 CPU 核数。然而，对于 Easysearch 这样精密设计的分布式数据库而言，性能的上限不取决于硬件的绝对值，而取决于软件对硬件资源的驾驭能力。 INFINI Easysearch 之所以能在国产化硬件和有限资源下跑出令人惊讶的性能，归功于它在**内存管理（Memory）、磁盘存储（Disk）和缓存机 … - [分片分配集群并发恢复配置](https://easysearch.cn/knowledge-base/easysearch_config/cluster.routing.allocation.cluster_concurrent_recoveries/): 配置项作用 # cluster.routing.allocation.cluster_concurrent_recoveries 配置项控制整个集群内同时进行的恢复操作的最大数量。 是否可选 # 是 默认值 # -1 (无限制) 配置项类型 # 动态配置 - 可以在运行时修改 配置格式 # # 默认配置（无限制） … - [在非主节点上刷新异常检测器内存请求 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/request-to-refresh-anomaly-detector-memory-requirement-on-non-master-node-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.12-8.4 1. 错误异常的基本描述 # 在非主节点上刷新异常检测器内存请求 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [字段名是元数据字段，无法在文档内部添加 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/field-name-is-a-metadata-field-and-cannot-be-added-inside-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.1-7.15 1. 错误异常的基本描述 # 字段名是元数据字段，无法在文档内部添加 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [意外地从只读仓库删除路径 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unexpectedly-deleting-path-from-a-readonly-repository-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.2 1. 错误异常的基本描述 # unexpectedly deleting path from a readonly repository 不是普通业务请求报错，而是一个明显带有保护性质的内部异常。它说明某段代码正在尝试从只读仓库中删除路径，而 Elasticsearch 认为这在语义上不应该发生，因此主动抛错阻止。换句话说，这类报错往往意味着仓库的只读边界被某个维护 … - [摄取节点配置](https://easysearch.cn/knowledge-base/easysearch_config/node.ingest/): 配置项作用 # node.ingest 配置项用于控制节点是否可以作为摄取节点（Ingest Node）运行。 摄取节点能够执行摄取管道（Ingest Pipeline），在文档被索引之前对其进行预处理。摄取管道由一系列处理器组成，可以执行诸如提取字段、重命名字段、解析 JSON、地理点处理等操作。 注意：此配置项已被废弃，推荐使用 node.roles 配置来替代。 配置项属性 # 配置路 … - [无效的小时值期望字符串或数值但找到了其他类型 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/invalid-hour-value-expected-string-number-value-but-found-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # 无效的小时值期望字符串或数值但找到了其他类型 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法启动汇总索引创建失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unable-to-start-rollup-index-creation-failed-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.11-7.11 1. 错误异常的基本描述 # 无法启动汇总索引创建失败 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法在写入器上打开读取器 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-open-reader-on-writer-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 无法在写入器上打开读取器 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法在禁用索引和文档值的字段上定义脚本 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-define-script-on-field-with-index-false-and-doc-values-false-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.13-8.9 1. 错误异常的基本描述 # 无法在禁用索引和文档值的字段上定义脚本 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法提取请求体 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-extract-body-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 无法提取请求体 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返回 400、404、409、429、500 … - [显著性启发式解析失败：出现未知对象 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-significance-heuristic-unknown-object-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.5 1. 错误异常的基本描述 # 在使用 Elasticsearch 的 significant_terms 聚合时，如果为启发式（significance heuristic）配置了不被当前启发式类型支持的字段或对象，Elasticsearch 会在解析阶段抛出如下异常： failed to parse [heuristic] significance … - [查询节点](https://easysearch.cn/knowledge-base/easysearch_api/get-node/): 此 API 用于显示集群中所有节点的详细信息和统计指标。 API # GET /_cat/nodes API 的作用 # 返回集群中所有节点的全面信息，包括： 基本信息：节点 ID、名称、IP 地址、端口等 版本信息：Easysearch 版本、构建信息、JDK 版本 资源使用：磁盘、内存、CPU 使用情况 统计信息：索引、搜索、合并等操作的统计数据 角色信息：主节点标记、节点角色（数据/摄 … - [模板不能为空 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/template-must-not-be-empty-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 模板不能为空 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [没有找到分析集合——如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/no-such-analytics-collection-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.8-8.9 1. 错误异常的基本描述 # 没有找到分析集合— 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [源索引已删除或关闭 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/source-indices-have-been-deleted-or-closed-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.3-8.9 1. 错误异常的基本描述 # 源索引已删除或关闭 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [管道期望恰好一个参数但发现多个——如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/pipe-expects-exactly-one-argument-but-found-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.9-8.9 1. 错误异常的基本描述 # 管道期望恰好一个参数但发现多个— 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [索引创建失败 (index_creation_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/index_creation_exception/): 为什么这个错误发生 # index_creation_exception 表示在创建索引时发生错误。这是一个包装异常，实际的失败原因在 cause 中。 这个错误可能由以下原因引起： 索引已存在：尝试创建同名的索引 无效的索引名：索引名不符合命名规范 映射错误：索引映射定义有误 设置冲突：索引设置之间存在冲突 分片分配失败：无法分配主分片 资源不足：节点磁盘空间或内存不足 主节点问题：主节点不 … - [纬度必须是数字 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/latitude-must-be-a-number-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 纬度必须是数字 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [脚本异常 (script_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/script_exception/): 为什么这个错误发生 # script_exception 表示在执行脚本（如 Painless、Groovy 等）时发生错误。脚本常用于更新、聚合、评分等操作。 这个错误可能由以下原因引起： 语法错误：脚本代码语法不正确 编译错误：脚本无法被编译 运行时错误：脚本执行过程中发生错误 字段不存在：访问不存在的文档字段 类型错误：操作的数据类型不匹配 权限错误：脚本被安全策略阻止 超时：脚本执行时 … - [节点未连接 – 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/node-not-connected-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 节点未连接 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返回 400、404、409、429、500 … - [节点级写入字节数限制配置](https://easysearch.cn/knowledge-base/easysearch_config/cluster.throttle.node.write.max_bytes/): 配置项作用 # 设置节点级别每秒允许的最大写入字节数。 默认值 # 0b（不限制） 配置格式 # # 每秒最多 100MB cluster.throttle.node.write.max_bytes: 100mb # 不限制字节数（默认） cluster.throttle.node.write.max_bytes: 0b - [解析 Action Status 时失败执行缺少必填字段 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-action-status-for-missing-required-field-for-unsuccessful-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # could not parse action status for [actionId]. missing required field for unsuccessful execution [last_execution.reason] 是 Elasticsearch Watcher 组件在解析 Action 执行状态时抛出的解析异 … - [预期字段名为 commands 但收到其他值 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/expected-field-name-to-be-named-commands-got-instead-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 预期字段名为 commands 但收到其他值 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [a query cannot be repeated more than 100 times found - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/a-query-cannot-be-repeated-more-than-100-times-found-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.16-8.9+ 1. 错误异常的基本描述 # a query cannot be repeated more than 100 times; found [value] 是 Elasticsearch 在解析 span query（跨度查询）时抛出的参数验证异常。当你在某个需要 runs 参数的 span query 中提供了超过 100 的值时，就会触发此错误。根据源 … - [aborting operation during - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/aborting-operation-during-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.11+ 1. 错误异常的基本描述 # aborting operation during [operation] as it has taken longer than the timeout of [timeout] 是 Elasticsearch 的 TimeoutChecker（超时检查器）抛出的超时异常。当某个操作（如搜索、写入、快照等）的执行时间超过了预设的超 … - [could not parse input for watch unknown content type - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-input-for-watch-unknown-content-type-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # could not parse [http] input for watch [id]. unknown content type [value] 是 Elasticsearch Watcher 组件在解析 http 类型 input 时抛出的解析异常。当 Watcher 尝试读取 HTTP input … - [could not parse time time minute is not a number - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-time-time-minute-is-not-a-number-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # could not parse time [value]. time minute [m] is not a number 是 Elasticsearch 在解析时间字符串时抛出的异常。此错误表示时间字符串的 minute 部分（冒号后的部分）不能被解析成整数。 该错误发生在 hh:mm 格式通过初步检查后，minute 片段包含非数字 … - [Easysearch 安装目录配置](https://easysearch.cn/knowledge-base/easysearch_config/path.home/): 配置项作用 # path.home 配置项用于指定Easysearch 的安装根目录。 这是 Easysearch 配置中最基础也是最重要的路径设置，作为所有其他相对路径的基准。包含二进制文件、配置文件、模块、插件等核心组件。 配置项属性 # 配置路径: path.home 数据类型: String（目录路径） 默认值: 无（必须配置） 是否可选: 否（必须配置） 作用域: … - [Easysearch 性能优化实践：高并发、大数据量下的索引与搜索优化](https://easysearch.cn/knowledge-base/perf/easysearch-performance-optimization-guide/): 在大数据与人工智能飞速发展的今天，企业对于搜索引擎的性能要求日益严苛。无论是海量的日志分析、实时的业务监控，还是面向用户的精准搜索，系统都需要在高并发写入和大规模数据检索的双重压力下保持毫秒级的响应速度。 INFINI Easysearch 作为一款基于 Apache Lucene 开发的分布式近实时搜索与分析引擎，不仅完美兼容 Elasticsearch 原生生态，更在内核层面进行了深度优化。本 … - [hour 值超出 0-23 范围 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/invalid-time-hour-value-possible-values-may-be-between-0-and-23-incl-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # invalid time hour value [n] (possible values may be between 0 and 23 incl.) 是 Elasticsearch 在解析时间表达式（常见于 Watcher 的 trigger 调度配置）时抛出的异常。该错误表示 hour 字段已被成功解析为数字，但数值不在 0 … - [HTTP CORS 跨域配置](https://easysearch.cn/knowledge-base/easysearch_config/http.cors.enabled/): 配置项作用 # http.cors.enabled 配置项控制是否启用跨域资源共享 (CORS) 支持，允许 Web 应用程序从不同域名访问 Easysearch HTTP API。 是否可选 # 是 默认值 # false (禁用 CORS) 配置项类型 # 静态配置 - 需要重启节点才能生效 配置格式 # # 启用 CORS http.cors.enabled: true # … - [No commands - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/no-commands-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # No commands 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Node currentNodes getLocalNode not master for join request – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/node-currentnodes-getlocalnode-not-master-for-join-request-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Node currentNodes getLocalNode not master for join request 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要 … - [Range query 不支持 currentFieldName – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/range-query-does-not-support-currentfieldname-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Range query 不支持 currentFieldName 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Watcher报告：在JSON负载中找到字段路径](https://easysearch.cn/knowledge-base/elasticsearch_error/watch-reporting-field-path-found-in-json-payload-payload-was-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # Watcher报告：在JSON负载中找到字段路径 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返 … - [Wrong value for termVector termVector for field fieldName - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/wrong-value-for-termvector-termvector-for-field-fieldname-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.9 1. 错误异常的基本描述 # Wrong value for termVector termVector for field fieldName 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日 … - [分片已迁移 (index_shard_relocated_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/index_shard_relocated_exception/): 为什么这个错误发生 # index_shard_relocated_exception 表示分片已经迁移到其他节点。 如何修复 # 1. 检查分片位置 # GET /_cat/shards?v&h=index,shard,node,state 2. 无需操作 # 分片迁移是正常状态。 预防措施 # 避免在迁移时操作分片 - [创建转换通知索引失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failure-creating-transform-notification-index-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.16-8.9 1. 错误异常的基本描述 # 创建转换通知索引失败 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [广播分片操作失败异常 (broadcast_shard_operation_failed_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/broadcast_shard_operation_failed_exception/): 为什么这个错误发生 # broadcast_shard_operation_failed_exception 表示在对多个分片执行广播操作时，一个或多个分片上的操作失败。广播操作是指需要在索引的所有分片（或多个分片）上执行的操作，如刷新、合并、更新映射等。 这个错误可能由以下原因引起： 分片不可用：目标分片处于不可用状态（未分配、正在迁移等） 分片正在恢复：分片正在进行恢复操作，暂时无法处理请 … - [异步搜索通用线程池最大大小配置](https://easysearch.cn/knowledge-base/easysearch_config/thread_pool.async_search_generic.max/): 配置项作用 # thread_pool.async_search_generic.max 配置项用于控制异步搜索通用线程池的最大线程数。 这是线程池能够创建的最大线程数量上限，用于限制资源消耗，防止系统过载。 配置项属性 # 配置路径: thread_pool.async_search_generic.max 数据类型: Integer（整数） 默认值: 动态计算 min(2 × … - [意外的标记，期望对象](https://easysearch.cn/knowledge-base/elasticsearch_error/unexpected-token-token-expected-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 意外的标记，期望对象 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法列出分片目录内容 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-list-content-of-shard-directory-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.4-7.7 1. 错误异常的基本描述 # 无法列出分片目录内容 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法解析字段提升参数 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-parse-boosting-for-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 无法解析字段提升参数 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法解析监视器条件，脚本定义解析失败（Could not parse condition for watch. failed to parse script）- 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-condition-for-watch-failed-to-parse-script-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.x 1. 错误异常的基本描述 # could not parse [script] condition for watch [...]. failed to parse script 是 Elasticsearch Watcher 在解析监视器（Watch）中定义的脚本条件时抛出的异常。该错误发生在 脚本解析阶段，而非脚本执行阶段，意味着 Elasticsearch 无 … - [无法解析监视器条件，遇到重复比较运算符（Could not parse condition for watch. encountered duplicate comparison operator）- 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-condition-for-watch-encountered-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.x 1. 错误异常的基本描述 # could not parse [compare] condition for watch [...]. encountered duplicate comparison operator; but already saw [...] 表示在同一个 compare 路径对象中，Watcher 发现了重复的比较运算定义。 例如一个路径下已 … - [期望值为对象但实际发现其他类型 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/expected-the-value-for-to-be-an-object-but-found-instead-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # expected the value for [name] to be an object, but found [token] instead 表示某个命名字段对应的值必须是一个对象，但请求里实际传的是别的 token 类型。 从当前页面保留的源码看，这类异常出现在按应用名或命名键逐项解析权限或配置定义时。也就是说，键名本身没问题， … - [未找到 searchable snapshot 索引 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/no-searchable-snapshots-indices-found-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.10-8.9 1. 错误异常的基本描述 # 这条 No searchable snapshots indices found 来自资源解析后的结果检查。源码会收集当前请求范围内所有 searchable snapshot 索引，如果最终集合为空，就抛出 ResourceNotFoundException。因此它表达的不是“快照仓库里没有 snapshot”，而是“当前这次操作没 … - [构建顶层 Pipeline 聚合结果失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-build-top-level-pipeline-aggregators-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Failed to build top level pipeline aggregators 是 Elasticsearch 在执行聚合查询时，于普通聚合阶段完成后、将 pipeline 聚合结果挂回最终响应的过程中抛出的异常。该错误意味着 Elasticsearch 无法正确地将顶层 pipeline aggregation 的结果组 … - [查询节点属性](https://easysearch.cn/knowledge-base/easysearch_api/get-node-attributes/): 此 API 用于显示集群中所有节点的自定义属性信息。 API # GET /_cat/nodeattrs API 的作用 # 返回集群中每个节点的属性信息，包括： 节点信息：节点名称、ID、进程 ID、主机名、IP 地址、端口 节点属性：节点的自定义属性名称和对应的值 节点属性用于在节点上存储自定义的键值对信息，常用于： 标记节点的物理位置（如机房、机架） 标记节点的硬件特性（ … - [索引 IndexNotFoundException e getIndex 未找到 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/index-indexnotfoundexception-e-getindex-was-not-found-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.2-7.15 1. 错误异常的基本描述 # 索引 IndexNotFoundException e getIndex 未找到 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判 … - [索引内存检查间隔配置](https://easysearch.cn/knowledge-base/easysearch_config/indices.memory.interval/): 配置项作用 # indices.memory.interval 配置项控制检查索引内存使用情况的间隔时间。系统定期检查索引缓冲区的内存使用，以便及时回收不再活跃分片的内存，防止内存泄漏和过度占用。 配置项类型 # 该配置项为静态配置，需要在启动时设置，修改后需要重启节点才能生效。 默认值 # 5s 是否必需 # 可选配置项（有默认值） 取值范围 # 0 ~ 正无穷 配置格式 # # 默 … - [索引缓冲区大小配置](https://easysearch.cn/knowledge-base/easysearch_config/indices.memory.index_buffer_size/): 配置项作用 # indices.memory.index_buffer_size 配置项控制用于索引操作的 JVM 堆内存总量。此内存被所有活跃索引的分片共享，用于提高索引性能。 配置项类型 # 该配置项为静态配置，需要在启动时设置，修改后需要重启节点才能生效。 默认值 # 10%（JVM 堆内存的 10%） 是否必需 # 可选配置项（有默认值） 配置格式 # # 百分比格式（默认） … - [节点处理器数量配置](https://easysearch.cn/knowledge-base/easysearch_config/node.processors/): 配置项作用 # node.processors 配置项用于控制节点使用的处理器（CPU 核心）数量。 此配置影响节点内部线程池的大小计算，是性能调优的重要参数。如果不配置，系统会自动检测可用的 CPU 核心数。 配置项属性 # 配置路径: node.processors 数据类型: Integer（整数值） 默认值: … - [认证未包含元数据 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/authentication-did-not-contain-metadata-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.2-8.9 1. 错误说明 # authentication did not contain metadata 是 Elasticsearch 安全模块在认证过程中抛出的 ElasticsearchSecurityException。该异常表示：当 Elasticsearch 尝试验证用户身份时，认证对象（Authentication）中缺少必要的元数据（metadata），导 … - [部分数据源升级失败 – 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/some-datafeeds-failed-being-upgraded-how-to-solve-this-elasticsearch-exception/): 适用版本： 8-8.9 1. 错误异常的基本描述 # 部分数据源升级失败 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [重复别名 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/duplicate-alias-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 重复别名 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返回 400、404、409、429、500 … - [预期几何类型但找到了其他类型 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/expected-geometry-type-but-found-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 预期几何类型但找到了其他类型 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [assignment for deployment with id not found - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/assignment-for-deployment-with-id-not-found-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.17-8.9 1. 错误说明 # assignment for deployment with id [xxx] not found 是 Elasticsearch 机器学习（Machine Learning）模块中的异常，完整异常类为 ResourceNotFoundException。当 Elasticsearch 尝试对某个已训练的模型（Trained Model）执行停 … - [Blob 存储异常 (blob_store_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/blob_store_exception/): 为什么这个错误发生 # blob_store_exception 是与二进制大对象（Blob）存储相关的通用异常。Blob 存储用于快照仓库、分恢复等场景，用于存储较大的二进制数据。 这个错误可能由以下原因引起： 仓库连接失败：无法连接到 Blob 存储系统（如 S3、Azure、HDFS） 认证失败：Blob 存储的认证凭据无效或过期 空间不足：Blob 存储空间不足 网络问题：与 Blob … - [boosting query requires negative query to be set - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/boosting-query-requires-negative-query-to-be-set-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.0-8.9 1. 错误异常的基本描述 # boosting query requires negative query to be set 是 Elasticsearch 在执行或解析 Boosting Query 时抛出的 illegal_argument_exception 或 parsing_exception。该错误明确表示：在构造 boosting 查询时，必须同时提 … - [Dis max 查询不支持 currentFieldName – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/dis-max-query-does-not-support-currentfieldname-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Dis max 查询不支持 currentFieldName 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Easysearch 性能指标与调优技巧实战：从分片策略到多级缓存的深度解析](https://easysearch.cn/knowledge-base/perf/easysearch-performance-metrics-tuning-guide/): 在企业级搜索与数据分析场景中，性能往往是衡量系统优劣的核心标准。作为一款自主可控、基于 Apache Lucene 构建的分布式近实时搜索与分析引擎，INFINI Easysearch 在保持与 Elasticsearch 高度兼容的同时，针对高并发、大数据量及复杂业务场景进行了深度的内核级优化。 本文将深入探讨 Easysearch 的核心性能指标，并结合实战案例，详细解析缓存策略、分片管理及副 … - [Failed to parse repository uuid not a string - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-repository-uuid-not-a-string-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.12-8.9 1. 错误异常的基本描述 # failed to parse repository [{}]; uuid not a string 表示 Elasticsearch 在解析 repository metadata 时，发现 uuid 字段存在，但它不是字符串类型。根据当前源码，解析器在遇到 uuid 字段时明确要求下一个 token … - [Fetch inner finish failed – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/fetch-inner-finish-failed-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Fetch inner finish failed 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返 … - [Geo distance 需要指定距离参数——如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/geo-distance-requires-distance-to-be-specified-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Geo distance 需要指定距离参数— 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Job 不存在 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/job-jobid-does-not-exist-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # job [jobId] does not exist 是 Elasticsearch 机器学习模块中常见的 ResourceNotFoundException 异常。该错误表示系统在当前的 job 集合中没有找到指定 jobId 对应的作业对象，导致后续操作（如删除、更新、关闭等）无法继续执行。 常见现象 # 调用删除、 … - [Setting setting getKey 为仓库空值 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/setting-setting-getkey-is-empty-for-repository-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # Setting [xxx] is empty for repository 表示 Elasticsearch 已经从 repository settings 中找到了对应键，但它的值是空字符串或只有空白字符。源码片段里可以看到，逻辑会先检查 setting 是否存在；若存在且为字符串， … - [Span near 查询不支持 currentFieldName - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/span-near-query-does-not-support-currentfieldname-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Span near 查询不支持 currentFieldName 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [从节点故障检测间隔配置](https://easysearch.cn/knowledge-base/easysearch_config/cluster.fault_detection.follower_check.interval/): 配置项作用 # cluster.fault_detection.follower_check.interval 配置项控制主节点向从节点发送健康检查请求的间隔时间。主节点需要定期检查所有从节点的健康状态，以确定集群成员是否仍然存活。此配置影响集群对从节点故障的响应速度。 配置项类型 # 该配置项为静态配置，需要在启动时设置，修改后需要重启节点才能生效。 默认值 # 1s 是否必需 # 可选 … - [分析线程池大小配置](https://easysearch.cn/knowledge-base/easysearch_config/thread_pool.analyze.size/): 配置项作用 # thread_pool.analyze.size 配置项用于控制分析线程池的固定线程数量。 分析线程池专门用于处理分析操作，包括 _analyze API 请求、文本分析和分词操作等。 配置项属性 # 配置路径: thread_pool.analyze.size 数据类型: Integer（整数） 默认值: 8 是否可选: 是 作用域: NodeScope（节点级别） 动态更 … - [分片关闭时不能打开 CCR restore session - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-open-ccr-restore-session-if-shard-closed-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 这里的 cannot open ccr restore session if shard closed 是一条非常直接的状态前置检查。源码在为某个分片打开新的 CCR restore session 之前，会先判断 indexShard.state()；只要状态是 IndexShardState.CLOSED， … - [向后兼容Ping超时配置](https://easysearch.cn/knowledge-base/easysearch_config/discovery.zen.bwc_ping_timeout/): 配置项作用 # discovery.zen.bwc_ping_timeout 配置项用于控制集群在滚动升级过程中向后兼容 ping 请求的超时时间。 此配置主要用于混合版本集群（同时包含旧版本和新版本节点）的升级过渡阶段。 配置项属性 # 配置路径: discovery.zen.bwc_ping_timeout 数据类型: TimeValue（时间值） 默认值: 1ms（1毫秒） 最小值: … - [启动数据分析 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/starting-data-frame-analytics-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.3-7.4 1. 错误异常的基本描述 # 启动数据分析 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返回 400、404、409、429、500 … - [字段 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-6.8 1. 错误异常的基本描述 # 字段 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返回 400、404、409、429、500 … - [字段名称必须指定path属性——如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/the-path-property-must-be-specified-for-field-name-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 字段名称必须指定path属性— 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [搜索失败并返回状态码 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/search-failed-with-status-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.16-8.9 1. 错误异常的基本描述 # 搜索失败并返回状态码 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [文档 currentDoc 获取阶段运行错误 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/error-running-fetch-phase-for-doc-currentdoc-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.6-8.9 1. 错误异常的基本描述 # 文档 currentDoc 获取阶段运行错误 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法在恢复时移除设置 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-remove-setting-ignoredsetting-on-restore-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # cannot remove setting [ignoredSetting] on restore 表示你在快照恢复请求中使用了 ignore_index_settings，想在恢复时移除某个索引设置，但该设置属于 Elasticsearch 明确禁止忽略或移除的受保护项。源码会先遍历 ignoreSettings， … - [无法对shape类型进行四舍五入 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/can-t-round-a-shape-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.6-8.9 1. 错误异常的基本描述 # 无法对shape类型进行四舍五入 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法执行批量操作 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/can-t-execute-a-bulk-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # 无法执行批量操作 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法解析电子邮件：出现意外字段 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-email-unexpected-field-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # 这个错误说明 Watcher 在解析邮件正文对象时，遇到了一个它不认识的字段。根据附带源码，这里校验的是 body 子对象内部字段，通常只接受 text 和 html。 典型报错形态类似： could not parse email. unexpected field [body.markdown] field 也就是说，问题通常不是 … - [构建 primaryName 时出错 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/error-building-primaryname-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 构建 primaryName 时出错 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [查询解释](https://easysearch.cn/knowledge-base/easysearch_api/get-explanation/): 计算查询与特定文档之间的评分，提供详细的评分计算过程。 API # GET /{index}/_explain/{id} POST /{index}/_explain/{id} GET /{index}/{type}/{id}/_explain POST /{index}/{type}/{id}/_explain API 的作用 # 该 API 用于解释为什么特定文档匹配或不匹配查询，返回： … - [正在使用的快照删除异常 (snapshot_in_use_deletion_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/snapshot_in_use_deletion_exception/): 为什么这个错误发生 # snapshot_in_use_deletion_exception 表示尝试删除正在被使用的快照。快照可能正在被恢复操作使用，或与其他快照有依赖关系。 这个错误可能由以下原因引起： 正在恢复：快照正在被用于恢复索引 快照依赖：其他快照依赖此快照 克隆操作：快照正在被用于克隆索引 搜索快照：快照正在被搜索 事务未完成：与快照相关的事务未完成 锁未释放：快照上的锁未正确释 … - [注册连接监听器配置](https://easysearch.cn/knowledge-base/easysearch_config/discovery.zen.fd.register_connection_listener/): 配置项作用 # discovery.zen.fd.register_connection_listener 配置项用于控制故障检测机制是否注册传输连接监听器到传输服务上。 连接监听器用于监听节点连接断开事件，当检测到连接断开时立即触发故障检测逻辑。 配置项属性 # 配置路径: discovery.zen.fd.register_connection_listener 数据类型: … - [类型出现意外的实际参数类型 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unexpected-actual-parameter-type-for-type-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 类型出现意外的实际参数类型 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [节点并发恢复数量配置](https://easysearch.cn/knowledge-base/easysearch_config/cluster.routing.allocation.node_concurrent_recoveries/): 配置项作用 # cluster.routing.allocation.node_concurrent_recoveries 配置项控制每个节点上允许同时进行的分片恢复操作的最大数量。此配置用于防止节点因过多的并发恢复操作而过载。 配置项类型 # 该配置项为动态配置，可以在运行时通过集群设置 API 进行修改。 默认值 # 2 是否必需 # 可选配置项（有默认值） 取值范围 # 0 ~ 正 … - [认证领域不存在 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/authenticating-realm-does-not-exist-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.2-8.9 1. 错误说明 # authenticating realm does not exist 是 Elasticsearch 安全模块在认证过程中抛出的异常，表示当前认证请求所引用的安全领域（Realm）在集群中不存在或无法被识别。 该异常通常出现在启用了 X-Pack Security 的集群中， … - [迁移用户 user 时失败并附带请求体 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-migrate-user-user-with-body-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.17 1. 错误异常的基本描述 # 迁移用户 user 时失败并附带请求体 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [选举未获胜 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/election-not-won-how-to-solve-this-elasticsearch-exception/): 适用版本： 7-8.9 1. 错误异常的基本描述 # 选举未获胜 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [集群信息更新间隔配置](https://easysearch.cn/knowledge-base/easysearch_config/cluster.info.update.interval/): 配置项作用 # cluster.info.update.interval 配置项用于控制 InternalClusterInfoService 集群信息服务的更新频率。 该服务定期收集集群中的关键信息，包括每个节点的磁盘使用情况、分片大小信息等，这些信息被用于路由决策、磁盘管理和分片平衡。 配置项属性 # 配置路径: cluster.info.update.interval 数据类型: … - [a following engine does not accept operations without an assigned sequence number - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/a-following-engine-does-not-accept-operations-without-an-assigned-sequence-number-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # a following engine does not accept operations without an assigned sequence number 是 Elasticsearch 在跨集群复制（CCR, Cross-Cluster Replication）或类似的数据复制场景中抛出的异常。跟随引擎（Following … - [cannot create job - 无法创建 Job 如何解决](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-create-job-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # Cannot create job [job_id] because it has already been created (task exists) 表示在 Elasticsearch 中创建 Rollup Job 或其他类型的持久化 Job 时，同名 Job 的持久化任务已经存在，导致创建操作失败。这是一个典型的资源冲突异常，底 … - [could not parse schedule could not parse as a duration - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-schedule-could-not-parse-as-a-duration-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # could not parse [type] schedule. could not parse [value] as a [unit] duration 是 Elasticsearch Watcher 在解析 schedule（调度）配置时抛出的异常。当 schedule 的持续时间（duration）数值部分无法转换为合法整数时，就 … - [failed to parse hipchat message, missing required field - 解析 HipChat 消息失败：缺少必需字段](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-hipchat-message-missing-required-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-6.8（HipChat 功能在更高版本中已废弃或移除） 1. 错误异常的基本描述 # 这个异常说明 HipChat message 的必填字段没有提供。根据附带源码，最典型的是 body 为空，解析器在读完整个消息对象后会直接拒绝。 典型报错： failed to parse hipchat message. missing required [body] field 从源 … - [Fetch Shard Started 线程池保活时间配置](https://easysearch.cn/knowledge-base/easysearch_config/thread_pool.fetch_shard_started.keep_alive/): 配置项作用 # thread_pool.fetch_shard_started.keep_alive 配置项用于控制分片启动状态获取线程池中弹性线程的保活时间。 当线程数超过核心线程数时，空闲的弹性线程在指定时间后会被回收，释放系统资源。 配置项属性 # 配置路径: thread_pool.fetch_shard_started.keep_alive 数据类型: TimeValue（时间值） … - [ISM 历史索引副本数配置](https://easysearch.cn/knowledge-base/easysearch_config/index_state_management.history.number_of_replicas/): 配置项作用 # index_state_management.history.number_of_replicas 配置项用于控制索引状态管理（ISM）历史索引的副本数量。 历史索引用于存储 ISM 策略执行的记录，包括状态变更、操作日志等信息。副本数影响历史数据的可用性和存储开销。 配置项属性 # 配置路径: … - [Pre tags 已设置但 post tags 未设置 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/pre-tags-are-set-but-post-tags-are-not-set-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.16-8.9 1. 错误异常的基本描述 # Pre tags 已设置但 post tags 未设置 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口 … - [rescore 窗口过大 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/rescore-window-rescorecontext-getwindowsize-is-too-large-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-6.8 1. 错误异常的基本描述 # 如果 rescore.window_size 设置过大，会看到报错： Rescore window [N] is too large. It must be less than [maxWindow]. 2. 为什么会发生这个错误 # rescore 只会对顶部若干命中做再次打分。窗口越大，需要暂存和重排的结果越多，内存消耗也越高。为 … - [term vectors 请求解析失败：出现未知字段 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-term-vectors-request-unknown-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # failed to parse term vectors request. unknown field [fieldName] 表示 Elasticsearch 在解析 Term Vectors API 请求时，发现了一个接口不支持的未知字段。Elasticsearch 对每个 REST API 都有严格的字段白名单校验机制，一旦请求中 … - [Translog 目录 translogPath 必须存在且为目录——如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/translog-directory-translogpath-must-exist-and-be-a-directory-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Translog 目录 translogPath 必须存在且为目录— 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现 … - [Transport TCP 地址重用配置](https://easysearch.cn/knowledge-base/easysearch_config/transport.tcp.reuse_address/): 配置项作用 # transport.tcp.reuse_address 配置项用于控制是否启用 SO_REUSEADDR 选项。 配置项属性 # 配置路径: transport.tcp.reuse_address 数据类型: Boolean（布尔值） 默认值: true（Linux/Unix）或 false（Windows） 是否可选: 是 作用域: NodeScope（节点级别） 动态更 … - [Wrapped DEK dekId 长度超出预期 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/wrapped-dek-dekid-is-larger-than-expected-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.12-8.6 1. 错误异常的基本描述 # Wrapped DEK [dekId] is larger than expected 表示 Elasticsearch 在读取内部保存的 wrapped DEK 时，发现对象内容比预期格式更长，存在额外尾部字节，因此认定该 DEK blob 已经不符合仓库加密格式。 这类异常属于数据完整性或格式一致性问题，不是简单的网络瞬时抖动。 … - [任务已取消 – 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/task-cancelled-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.12-8.9 1. 错误异常的基本描述 # 任务已取消 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [分片级写入限流启用配置](https://easysearch.cn/knowledge-base/easysearch_config/cluster.throttle.shard.write/): 配置项作用 # cluster.throttle.shard.write 配置项控制是否启用分片级别的写入限流功能。 默认值 # false 配置类型 # 动态配置 配置格式 # # 启用分片级写入限流 cluster.throttle.shard.write: true # 禁用（默认） cluster.throttle.shard.write: false 使用场景 # 分片级限流 … - [分词为空 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/tokenization-is-empty-how-to-solve-this-elasticsearch-exception/): 适用版本： 8-8.9 1. 错误异常的基本描述 # 分词为空 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返回 400、404、409、429、500 … - [创建 Blob 容器失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-create-blob-container-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 这条 failed to create blob container 来自具体 blob 容器或目录创建阶段。源码中先执行 mkdirs(path)；如果遇到 FileAlreadyExistsException 会被当作正常情况忽略，但其他 IOException … - [删除API密钥](https://easysearch.cn/knowledge-base/easysearch_api/delete-api-key/): 注意：DELETE /_security/api_key API 在当前版本的 Easysearch 中尚未实现服务器端。 API 说明 # DELETE /_security/api_key 端点在当前 Easysearch 版本中未实现服务器端 REST 处理器。 虽然客户端库中存在相关的数据结构类（如 ApiKey.java），但服务器端缺少相应的 REST 处理器来处理 API 密钥的删 … - [单数据节点启用磁盘水位线检查配置](https://easysearch.cn/knowledge-base/easysearch_config/cluster.routing.allocation.disk.watermark.enable_for_single_data_node/): 配置项作用 # cluster.routing.allocation.disk.watermark.enable_for_single_data_node 配置项用于控制当集群中只有一个数据节点时，是否强制启用磁盘水位线检查。 配置项属性 # 配置路径: cluster.routing.allocation.disk.watermark.enable_for_single_data_node … - [原因 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/reason-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.6-8.1 1. 错误异常的基本描述 # 原因 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返回 400、404、409、429、500 … - [参数 orientation 不支持该类型 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/parameter-orientation-is-not-supported-for-type-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.2-8.9 1. 错误异常的基本描述 # 参数 orientation 不支持该类型 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [大数据量分页，Easysearch 是如何避免性能陷阱的](https://easysearch.cn/knowledge-base/perf/easysearch-large-scale-pagination-performance-guide/): 在处理海量数据搜索时，“分页”往往是性能问题的重灾区。很多开发者习惯了 SQL 时代的 OFFSET + LIMIT 模式，将其直接迁移到 Easysearch 的 from + size 中。然而，随着数据量的增长，这种方式会导致查询延迟呈指数级上升，甚至拖垮整个集群。 本文将结合 Easysearch 的底层执行机制与官方文档规范，深入剖析分页性能陷阱的成因，并给出最佳实践方案。 性能陷阱：为 … - [字段映射器名称被多次定义 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/field-mapper-name-is-defined-more-than-once-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.1-8.9 1. 错误异常的基本描述 # 字段映射器名称被多次定义 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [异常 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/exception-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 异常 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返回 400、404、409、429、500 … - [必须为字段名指定dims属性 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/the-dims-property-must-be-specified-for-field-name-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.3-7.9 1. 错误异常的基本描述 # 必须为字段名指定dims属性 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法启动 Transform，分配说明显示失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-start-transform-allocation-explanation-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.5-8.9 1. 错误异常的基本描述 # Could not start transform; allocation explanation [...] 表示 Elasticsearch 尝试启动一个 Transform 持久化任务（Persistent Task），但该任务未能成功分配到任何可执行节点，因此无法真正开始工作。系统会将具体的失败原因写入 allocation … - [无法解析监视器条件，未知条件类型（Could not parse condition for watch. unknown condition type）- 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-condition-for-watch-unknown-condition-type-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.x 1. 错误异常的基本描述 # could not parse condition for watch [<watch_id>]. unknown condition type [<type>] 是 Elasticsearch Watcher 在解析监视器（watch）定义时抛出的异常。它表示 Watcher 在 condition 对象中找到 … - [期望对象但找到其他类型 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/expected-an-object-but-found-instead-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # expected an object but found [xxx] instead 是 Elasticsearch 在解析 JSON 请求体时抛出的典型异常，表示解析器在期望接收一个 JSON 对象（START_OBJECT）的位置，实际却遇到了其他类型的 token，例如字符串、数组、数值或 null。 … - [期望点 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/point-expected-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.8-8.2 1. 错误异常的基本描述 # 期望点 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返回 400、404、409、429、500 … - [段合并线程数配置](https://easysearch.cn/knowledge-base/easysearch_config/config_index.merge.scheduler.max_thread_count/): 配置项作用 # index.merge.scheduler.max_thread_count 配置项控制索引段合并操作的最大并发线程数。段合并是将多个小段合并为较大段的后台操作，此配置决定了可以同时执行多少个合并任务。 配置项类型 # 该配置项为动态配置，可以在运行时通过索引设置 API 进行修改。 默认值 # Math.max(1, Math.min(4, CPU核心数 / 2)) 示例： … - [汇总作业状态更新错误 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/error-while-updating-state-for-rollup-job-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # 汇总作业状态更新错误 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [没有可用于此凭据的私钥 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/there-is-no-private-key-available-for-this-credential-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.7-8.9 1. 错误异常的基本描述 # 没有可用于此凭据的私钥 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [短语建议器不支持字段 currentFieldName – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/suggester-phrase-doesn-t-support-field-currentfieldname-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.16-8.9 1. 错误异常的基本描述 # 短语建议器不支持字段 currentFieldName 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口 … - [索引没有主分片——如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/indices-don-t-have-primary-shards-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.6-8.9 1. 错误异常的基本描述 # 索引没有主分片— 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [网关异常 (gateway_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/gateway_exception/): 为什么这个错误发生 # gateway_exception 是与集群元数据持久化和恢复相关的异常。网关负责在集群启动时恢复状态。 这个错误可能由以下原因引起： 元数据损坏：集群元数据文件损坏 数据目录问题：数据目录权限或配置错误 版本不兼容：元数据版本与集群版本不兼容 磁盘问题：磁盘故障导致元数据无法读取 并发写入冲突：多个节点同时写入元数据 如何修复这个错误 # 1. 检查数据目录 # … - [解析长整型设置失败 setting 值为 sValue - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-long-setting-setting-with-value-svalue-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 解析长整型设置失败 setting 值为 sValue 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可 … - [集群阻塞异常 (cluster_block_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/cluster_block_exception/): 为什么这个错误发生 # cluster_block_exception 表示集群或索引被阻止执行某些操作。集群阻塞是一种保护机制，用于在特定情况下防止数据不一致或集群状态恶化。 这个错误可能由以下原因引起： 集群正在进行恢复：集群正在从数据恢复中，阻止写入操作 节点数量不足：候选主节点数量未达到法定人数 磁盘空间不足：磁盘水位线触发，阻止写入操作 索引正在创建或删除：索引处于中间状态 只读模 … - [base64_credentials option is required for cleaning up gcs repository - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/base64-credentials-option-is-required-for-cleaning-up-gcs-repository-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.6-7.17 1. 错误异常的基本描述 # base64_credentials option is required for cleaning up GCS repository 表示 Elasticsearch 在执行 GCS 快照仓库 cleanup 时，没有拿到用于访问 Google Cloud Storage 的 base64 编码凭证。对于依赖显式服务账号密钥的仓库 … - [bucketOrds 迭代顺序在没有变更的情况下发生变化 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/iteration-order-of-bucketords-changed-without-mutating-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.9-7.15 1. 错误异常的基本描述 # bucketOrds 迭代顺序在没有变更的情况下发生变化 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接 … - [failed to parse data frame stats from search hit - 无法从搜索结果中解析数据框统计信息](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-data-frame-stats-from-search-hit-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.2-7.4（后续版本中已迁移到 Transform） 1. 错误异常的基本描述 # failed to parse data frame stats from search hit 是早期 Data Frame Transform 读取内部统计文档时抛出的解析异常。其本质与后续版本中的 transform stats 异常一致，都是系统索引中的统计 _source 无法按预期结 … - [failed to parse hipchat message, unexpected field - 解析 HipChat 消息失败：出现意外字段](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-hipchat-message-unexpected-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-6.8（HipChat 功能在更高版本中已废弃或移除） 1. 错误异常的基本描述 # failed to parse hipchat message. unexpected field [{}] 表示 Elasticsearch Watcher 在解析 HipChat 消息时，发现了消息对象中包含解析器未定义的字段名， … - [failed to parse repositories - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-repositories-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # failed to parse repositories 通常出现在 Elasticsearch 读取或恢复仓库元数据时。它不是某个单独字段的小问题，而是 repositories 整体结构无法按预期解析。 常见现象 # 节点启动、集群状态恢复、读取仓库定义时失败。 往往会伴随更具体的内层异常，例如 missing … - [ISM 协调器重试次数配置](https://easysearch.cn/knowledge-base/easysearch_config/index_state_management.coordinator.backoff_count/): 配置项作用 # index_state_management.coordinator.backoff_count 配置项用于控制索引状态管理（ISM）协调器在操作失败后的最大重试次数。 当协调器执行批量操作失败时（如遇到 429 Too Many Requests 错误），系统会根据此配置进行重试。 配置项属性 # 配置路径: … - [privileges check 解析失败：应为对象却收到其他类型 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-privileges-check-expected-an-object-but-found-instead-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # 在执行权限检查时，如果请求体顶层不是一个 JSON 对象，Elasticsearch 会报： failed to parse privileges check [description]. expected an object but found [TOKEN] instead 2. 为什么会发生这个错误 # 这不是鉴权失败，而是请 … - [Search 线程池最大队列大小配置](https://easysearch.cn/knowledge-base/easysearch_config/thread_pool.search.max_queue_size/): 配置项作用 # thread_pool.search.max_queue_size 配置项用于控制搜索线程池队列的最大容量。 当队列达到此大小时，新的搜索请求将被拒绝。 配置项属性 # 配置路径: thread_pool.search.max_queue_size 数据类型: Integer（整数） 默认值: 1000 是否可选: 是 作用域: NodeScope（节点级别） 动态更新: … - [Transform 断路器启用配置](https://easysearch.cn/knowledge-base/easysearch_config/transform.circuit_breaker.enabled/): 配置项作用 # transform.circuit_breaker.enabled 配置项用于控制是否启用 Transform 任务的断路器机制。 当启用时，Transform 任务会在 JVM 内存使用率超过阈值时暂停执行，防止内存溢出。 配置项属性 # 配置路径: transform.circuit_breaker.enabled 数据类型: Boolean（布尔值） 默认值: true … - [主分片未分配 (index_primary_shard_not_allocated_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/index_primary_shard_not_allocated_exception/): 为什么这个错误发生 # index_primary_shard_not_allocated_exception 表示索引的主分片没有被分配到任何节点。主分片是处理写入操作的主要分片，必须在可用后才能执行写操作。 这个错误可能由以下原因引起： 节点离线：主分片所在的节点离线或宕机 磁盘空间不足：所有可用节点的磁盘空间不足 分配被禁用：分片分配被手动禁用 分片数据损坏：主分片数据损坏 分配过滤规 … - [分片与所需最低版本不兼容 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/one-of-the-shards-is-incompatible-with-the-required-minimum-version-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.12-8.9 1. 错误异常的基本描述 # 分片与所需最低版本不兼容 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [删除安全角色](https://easysearch.cn/knowledge-base/easysearch_api/delete-security-role/): 从 Easysearch 安全配置中删除指定的角色。 API 格式 # DELETE /_security/role/{name} API 作用 # 该 API 用于从集群的安全配置中删除角色： 删除角色及其所有关联的权限 更新集群的安全配置 立即移除被映射用户的相应权限 API 参数 # 路径参数 # 参数 类型 是否必填 默认值 描述 {name} String … - [参数不支持 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/parameter-not-supported-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 参数不支持 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [处理器不支持一个或多个提供的配置参数 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/processor-doesn-t-support-one-or-more-provided-configuration-parameters-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # 处理器不支持一个或多个提供的配置参数 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [多次尝试后索引所有结果失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-index-all-results-after-attempts-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # 多次尝试后索引所有结果失败 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [字段 fieldName 的 fields 属性期望为 map 类型，但得到了其他类型 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/expected-map-for-property-fields-on-field-fieldname-but-got-a-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # 字段 fieldName 的 fields 属性期望为 map 类型，但得到了其他类型 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一 … - [开箱即用：使用 Easysearch 快速构建你的第一个日志分析平台](https://easysearch.cn/knowledge-base/best/easysearch-quick-start-log-analysis-platform/): 在当今的数字化运维和业务监控中，日志数据被誉为“蕴含金矿的沙砾”。无论是排查故障、监控服务器指标，还是分析用户行为，一套高效、实时的日志分析平台都是必不可少的。 传统的 ELK（Elasticsearch, Logstash, Kibana）栈虽然强大，但往往面临资源消耗高、维护复杂、存储成本昂贵等痛点。INFINI Easysearch 的出现，为企业提供了一个更轻量、更高效、且完全兼容现有生态 … - [意外的标记，期望其他标记](https://easysearch.cn/knowledge-base/elasticsearch_error/unexpected-token-token-expected-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.17 1. 错误异常的基本描述 # 意外的标记，期望其他标记 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [意外错误](https://easysearch.cn/knowledge-base/elasticsearch_error/unexpected-error-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 意外错误 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法为反序列化生成错误消息——如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-generate-error-message-for-deserialization-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 无法为反序列化生成错误消息— 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法写入Kibana详情ZIP文件 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-write-kibana-details-zip-file-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.6-8.9 1. 错误异常的基本描述 # 无法写入Kibana详情ZIP文件 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法确定索引名称长度 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unable-to-determine-length-of-index-name-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8 1. 错误异常的基本描述 # 无法确定索引名称长度 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法解析主机 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-resolve-host-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 无法解析主机 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返回 400、404、409、429、500 … - [无法解析选项中的条目 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-parse-entry-in-options-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 无法解析选项中的条目 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [构建 XContent 失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-build-xcontent-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Failed to build xcontent 是 Elasticsearch 在执行对象序列化时抛出的异常，表示某个对象无法通过 XContentBuilder 正确构建为 JSON 或其他 XContent 格式（如 CBOR、YAML）。 该异常通常出现在以下场景： 集群状态变更时，节点需要将内部对象序列化后通过网络传输 快 … - [架构揭秘：Easysearch 如何实现高性能与高可用？](https://easysearch.cn/knowledge-base/perf/easysearch-architecture-secrets-high-performance-availability/): 在分布式系统的世界里，性能与可用性往往是一对需要权衡的矛盾体。作为基于 Apache Lucene 构建的分布式近实时搜索与分析引擎，INFINI Easysearch 通过精密的架构设计，不仅继承了 Lucene 强大的检索能力，更在分布式协调、存储引擎优化、内存管理等内核层面进行了大量重构与增强。 本文将结合架构图解，深入 Easysearch 的内核，从分布式拓扑、读写底层原理、存储机制等维 … - [每节点状态操作连接数配置](https://easysearch.cn/knowledge-base/easysearch_config/transport.connections_per_node.state/): 配置项作用 # transport.connections_per_node.state 配置项控制集群中每个节点之间用于状态操作（State Operations）的并发连接数。状态操作主要用于集群状态更新、元数据传输等内部管理操作。这是使用频率最低但非常重要的连接类型。 配置项类型 # 该配置项为静态配置，需要在启动时设置，修改后需要重启节点才能生效。 默认值 # 1 是否必需 # 可 … - [没有可用的身份验证来生成API密钥 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/no-authentication-available-to-generate-api-key-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.7-8.3 1. 错误异常的基本描述 # 没有可用的身份验证来生成API密钥 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [私钥使用了不支持的密钥算法类型 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/the-private-key-uses-unsupported-key-algorithm-type-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.7-7.15 1. 错误异常的基本描述 # 私钥使用了不支持的密钥算法类型 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [管理操作线程池配置](https://easysearch.cn/knowledge-base/easysearch_config/thread_pool.management/): 配置项作用 # thread_pool.management 相关配置项控制用于执行集群管理操作的线程池。管理操作包括集群状态更新、分片分配决策等集群级别的管理任务。该线程池采用伸缩线程池类型。 配置项类型 # 该配置项为静态配置，需要在启动时设置，修改后需要重启节点才能生效。 默认值 # thread_pool.management.core: 1 … - [索引状态管理快照拒绝列表配置](https://easysearch.cn/knowledge-base/easysearch_config/index_state_management.snapshot.deny_list/): 配置项作用 # index_state_management.snapshot.deny_list 配置项用于定义不允许被包含在快照操作中的索引模式列表。 配置项属性 # 配置路径: index_state_management.snapshot.deny_list 数据类型: List<String>（字符串列表） 默认值: 空列表 []（不拒绝任何索引） 是否可选: 是 作用 … - [设置必须大于零 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/setting-must-be-greater-than-zero-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.16-8.9 1. 错误异常的基本描述 # 设置必须大于零 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [高亮字段失败 highlighterContext fieldName – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-highlight-field-highlightercontext-fieldname-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.4 1. 错误异常的基本描述 # 高亮字段失败 highlighterContext fieldName 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 … - [could not parse message attachment field found field but no is - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-message-attachment-field-found-field-but-no-is-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # could not parse message attachment field. found field [X]; but no [Y] is defined 是 Elasticsearch Watcher 在解析消息附件（message attachment）时抛出的异常。此错误表示附件配置中某个字段存在，但其依赖的必需字段却未定 … - [HTTP 请求头最大大小配置](https://easysearch.cn/knowledge-base/easysearch_config/http.max_header_size/): 配置项作用 # http.max_header_size 配置项限制 HTTP 请求头的最大大小，防止客户端发送过大的请求头耗尽服务器资源。 是否可选 # 是 默认值 # 8kb 配置项类型 # 静态配置 - 需要重启节点才能生效 配置格式 # # 默认配置 http.max_header_size: 8kb # 增加限制 http.max_header_size: 16kb # 减少限 … - [ISM 历史索引滚动检查周期配置](https://easysearch.cn/knowledge-base/easysearch_config/index_state_management.history.rollover_check_period/): 配置项作用 # index_state_management.history.rollover_check_period 配置项用于控制ISM 历史索引执行滚动和过期清理操作的检查周期。 系统会按照此配置的周期定期检查历史索引是否需要滚动（满足 max_docs 或 max_age 条件），以及是否有过期索引需要删除。 配置项属性 # 配置路径: … - [Multiple default Azure data stores configured - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/multiple-default-azure-data-stores-configured-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-6.8 1. 错误异常的基本描述 # 这条异常说明 Azure repository 配置里有不止一个 storage setting 被标记为默认。源码在选主配置时发现第二个默认项后，会直接抛出 SettingsException。 常见现象 # Azure 仓库初始化失败。 日志里会列出两个冲突的默认配置名。 常见于复制配置模板后忘记取消旧默认项。 典型报错与异常 … - [Refresh 线程池最大大小配置](https://easysearch.cn/knowledge-base/easysearch_config/thread_pool.refresh.max/): 配置项作用 # thread_pool.refresh.max 配置项用于控制索引刷新线程池的最大线程数。 配置项属性 # 配置路径: thread_pool.refresh.max 数据类型: Integer（整数） 默认值: (CPU核心数 + 1) / 2，最大不超过 10 是否可选: 是 作用域: NodeScope（节点级别） 动态更新: 是（可以动态更新，无需重启） … - [Rollup 搜索重试延迟配置](https://easysearch.cn/knowledge-base/easysearch_config/rollup.search.backoff_millis/): 配置项作用 # rollup.search.backoff_millis 配置项用于控制Rollup 搜索操作每次重试之间的等待时间。 当 Rollup 搜索操作失败后，系统会等待此配置指定的时间后再进行下一次重试，用于避免过快重试导致系统压力过大。 配置项属性 # 配置路径: rollup.search.backoff_millis 数据类型: TimeValue（时间值） 默认值: … - [传统方案的平滑升级：从 Elasticsearch 迁移到 Easysearch 实战指南](https://easysearch.cn/knowledge-base/best/elasticsearch-to-easysearch-migration-guide/): 传统方案的平滑升级：从 Elasticsearch 迁移到 Easysearch 实战指南 在国产化替代和降本增效的浪潮下，越来越多的企业选择将 Elasticsearch (ES) 替换为 INFINI Easysearch。然而，对于核心业务系统而言，“替换数据库”无异于“给飞行中的飞机换引擎”。 数据会不会丢？业务要不要停机？代码要不要改？升级失败能不能回退？ 本文将抛弃传统的“停机导出导 … - [使源前缀失效时出错 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/error-invalidating-srcprefix-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 使源前缀失效时出错 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [使用双引号定义字符串字面量而不是单引号 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/use-double-quotes-to-define-string-literals-not-single-quotes-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # 使用双引号定义字符串字面量而不是单引号 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [创建API密钥](https://easysearch.cn/knowledge-base/easysearch_api/create-api-key/): 注意：POST /_security/api_key API 在当前版本的 Easysearch 中尚未实现服务器端。 API 说明 # POST /_security/api_key 端点在当前 Easysearch 版本中未实现服务器端 REST 处理器。 虽然客户端库中存在相关的数据结构类（如 CreateApiKeyResponse.java），但服务器端缺少相应的 REST 处理器来处 … - [只读模式下添加索引块请求未被确认 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/read-only-add-block-index-request-failed-to-be-acknowledged-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.11-8.9 1. 错误异常的基本描述 # 只读模式下添加索引块请求未被确认 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [基础路径中不应有尾部斜杠 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/there-should-be-no-trailing-slash-in-the-base-path-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.6-7.17 1. 错误异常的基本描述 # there should be no trailing slash in the base path 是一个配置校验类异常，通常出现在快照仓库相关操作中，表示传入的 base_path 末尾多写了一个 /。这个错误不属于网络、节点或分片故障，而是请求参数格式在进入实际执行前就被 Elasticsearch 判定为不合法。 从当前日志片 … - [嵌套对象映射的include_in_root参数无法更新 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/the-include-in-root-parameter-can-t-be-updated-for-the-nested-object-mapping-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.8-7.8 1. 错误异常的基本描述 # 嵌套对象映射的include_in_root参数无法更新 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口 … - [建议器缺少必填 field 选项 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/the-required-field-option-fieldname-field-getpreferredname-is-missing-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.16-8.9 1. 错误异常的基本描述 # the required field option [field] is missing 是 Elasticsearch 在解析 建议器（Suggester） 配置时抛出的 ElasticsearchParseException。该错误表示某个建议器对象中缺少必填的 field 参数，导致 Elasticsearch 无法完成建议器的 … - [性能飞跃的背后：详解 Easysearch 的写入与查询优化黑科技](https://easysearch.cn/knowledge-base/perf/easysearch-performance-leap-write-query-optimization/): 在数据爆炸的今天，企业对于搜索引擎的期待早已超越了简单的“能查”，而是转向了“快写”、“秒查”以及“低成本存储”。作为一款基于 Apache Lucene 开发的分布式近实时搜索与分析引擎，INFINI Easysearch 在继承 Elasticsearch 优秀基因的同时，针对中国企业级场景进行了深度的内核级优化。 本文将深入剖析 Easysearch 在写入性能与查询效率两大核心维度的“黑科 … - [无法启动 Datafeed - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-start-datafeed-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # cannot start datafeed [datafeed_id] because it has already been started 表示某个 datafeed 已经处于运行状态，但外部又发起了一次启动请求。Elasticsearch 会把这种重复启动视为状态冲突（409 CONFLICT），而不是内部故障。 常见现象 # … - [无法序列化 ID 为 updatedConfig getId 的数据馈送配置 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-serialise-datafeed-config-with-id-updatedconfig-getid-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 无法序列化 ID 为 updatedConfig getId 的数据馈送配置 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常 … - [无法执行时间序列聚合 (Could not perform time series aggregation) - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-perform-time-series-aggregation-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.1-8.9 1. 错误异常的基本描述 # Could not perform time series aggregation 是 Elasticsearch 在执行时间序列索引（time series index）上的聚合查询时抛出的运行时异常。该异常通常发生在搜索阶段，由 AggregationExecutionException 包装抛出，表示当前聚合上下文无法在时间序列索 … - [无法解析 inner _source 定义 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-inner-source-definition-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.x 1. 错误异常的基本描述 # Could not parse inner _source definition 发生在 inner_hits 配置解析阶段。inner_hits._source 支持布尔值、字符串、字符串数组，或带 includes/excludes 的对象；如果传入了不合法的结构，FetchSourceContext.fromXContent 就会 … - [无法解析指定的URL - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-parse-the-specified-url-url-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # 无法解析指定的URL 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法解析数据附件，字段期望字符串值（Could not parse data attachment. expected string value for [...] field）- 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-data-attachment-expected-string-value-for-field-but-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.x 1. 错误异常的基本描述 # could not parse data attachment. expected string value for [field_name] field but found [token_type] instead 是 Elasticsearch Watcher 组件在解析 data attachment（数据附件）配置时抛出的解析异 … - [无法解析该类型的附件（Cannot parse attachment of type [...]）- 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-parse-attachment-of-type-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.x 1. 错误异常的基本描述 # Cannot parse attachment of type [...] 表示 Elasticsearch Watcher 在解析邮件附件时，遇到了一个当前版本或当前 action 不支持的附件类型。异常会明确指出无法识别的类型名，例如： ElasticsearchParseException: Cannot parse … - [无法重构对象，无法解析分片的总计数 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unable-to-reconstruct-object-total-counts-for-shards-couldn-t-be-parsed-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.16-7.17 1. 错误异常的基本描述 # 无法重构对象，无法解析分片的总计数 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [状态异常 (status_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/status_exception/): 为什么这个错误发生 # status_exception 表示一个具有任意 HTTP 状态码的异常。这是一个包装异常，用于传递特定状态码的异常信息，通常用于包装远程异常或特定场景的错误响应。 这个错误可能由以下原因引起： 远程异常包装：包装来自远程节点的异常及其状态码 自定义状态响应：返回特定状态码的错误 跨集群操作：跨集群操作时的状态传递 客户端错误：4xx 系列错误 服务器错误：5xx 系 … - [类型为type的字段n不能用于多字段 – 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/field-n-of-type-type-can-t-be-used-in-multifields-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.14-8.9 1. 错误异常的基本描述 # 类型为type的字段n不能用于多字段 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [请求在非主节点上放置数据框架分析内存需求 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/request-to-put-data-frame-analytics-memory-requirement-on-non-master-node-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.12-8.4 1. 错误异常的基本描述 # 请求在非主节点上放置数据框架分析内存需求 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [远程集群客户端配置](https://easysearch.cn/knowledge-base/easysearch_config/node.remote_cluster_client/): 配置项作用 # node.remote_cluster_client 配置项用于控制节点是否允许作为远程集群客户端。 当启用时，节点可以连接到其他 Easysearch 集群，执行跨集群搜索（CCS）等操作。当禁用时，节点无法建立到远程集群的连接。 注意：此配置项已被废弃，推荐使用 node.roles 配置来替代。 配置项属性 # 配置路径: … - [远程集群节点属性筛选配置](https://easysearch.cn/knowledge-base/easysearch_config/cluster.remote.node.attr/): 配置项作用 # cluster.remote.node.attr 配置项用于指定远程集群中应该连接的节点的属性名称。 通过此配置，可以选择远程集群中具有特定属性的节点作为跨集群连接的网关节点，实现更精细的连接控制。 配置项属性 # 配置路径: cluster.remote.node.attr 数据类型: string 默认值: 无（空字符串） 是否可选: 是 作用域: 节点级 … - [非失败节点未形成法定人数 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/non-failed-nodes-do-not-form-a-quorum-how-to-solve-this-elasticsearch-exception/): 适用版本： 7-8.9 1. 错误异常的基本描述 # 非失败节点未形成法定人数 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Compressed stream is longer than maximum allowed bytes streamSize – How to solve this Elasticsearch exception](https://easysearch.cn/knowledge-base/elasticsearch_error/compressed-stream-is-longer-than-maximum-allowed-bytes-streamsize-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # Compressed stream is longer than maximum allowed bytes streamSize – How to solve this Elasticsearch exception 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题 … - [Easy-Es 框架深度集成-ORM 方式操作 Easysearch 的最佳实践](https://easysearch.cn/knowledge-base/best/easy-es-easysearch-orm-integration-best-practices/): 在很多企业项目里，“搜索”早已不是锦上添花，而是支撑 日志检索、告警排查、运营分析、内部统一搜索 的核心底座。 但在工程实践中，团队往往会同时面临两类现实问题： DSL 足够灵活，但代码量大、可读性差、维护成本高 索引创建/变更、Mapping 升级、数据迁移……一堆“脏活累活”容易出错 国产化/信创落地时，希望替换底层引擎，同时又希望尽量不改业务代码 这也是 Easysearch（分布式近实 … - [ES 国产化抉择：直面安全风险，为何 Easysearch 是优选方案？](https://easysearch.cn/knowledge-base/insight/es-domestic-replacement-facing-security-risks-why-easysearch-is-the-preferred-option/): 一封关于数据泄露的警报邮件在企业安全部门内部传阅，技术总监眉头紧锁，屏幕上显示的是已经暴露在公网上长达数周的 Elasticsearch 集群。 数据泄露的威胁正以惊人的速度增长。根据 Group-IB 的报告，仅在 2021 年，网络上暴露的 Elasticsearch 实例就超过 10 万个，约占当年暴露数据库总数的 30%。 从 2019 年泄露27 亿个电子邮件地址（其中 10 亿个为明 … - [KeyManagerFactory初始化失败 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-initialize-a-keymanagerfactory-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.3 1. 错误异常的基本描述 # KeyManagerFactory初始化失败 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [positions_increment_gap 必须为正数，得到 v – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/positions-increment-gap-must-be-positive-got-v-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.1-7.1 1. 错误异常的基本描述 # positions_increment_gap 必须为正数，得到 v 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 … - [Profile 不同iator 值对于 base Uid 过高 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/profile-differentiator-value-is-too-high-for-base-uid-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.2-8.9 1. 错误异常的基本描述 # Profile 不同iator 值对于 base Uid 过高 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [proxyBasePath 格式非法 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/concretesetting-getkey-is-malformed-proxybasepath-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # [<setting_key>] is malformed [<proxyBasePath>] 是 Elasticsearch 在初始化 HTTP 客户端（如 S3 仓库客户端、Azure 仓库客户端或其他基于 Apache HttpClient 的远程客户端）时抛出的 SettingsException。该错误 … - [Rollup Job 任务请求 getId 未找到 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/task-for-rollup-job-request-getid-not-found-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Rollup Job 任务请求 getId 未找到 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [source 字段类型非法 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/illegal-type-for-source-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # source 字段类型非法 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Span within little must be of type span query – 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/span-within-little-must-be-of-type-span-query-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Span within little must be of type span query 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态 … - [Transport Netty Worker 线程数配置](https://easysearch.cn/knowledge-base/easysearch_config/transport.netty.worker_count/): 配置项作用 # transport.netty.worker_count 配置项用于控制Netty Worker 线程的数量。 Worker 线程负责处理实际的 I/O 操作和业务逻辑。 配置项属性 # 配置路径: transport.netty.worker_count 数据类型: Integer（整数） 默认值: CPU核心数（availableProcessors） 是否可选: 是 作 … - [Write 线程池队列大小配置](https://easysearch.cn/knowledge-base/easysearch_config/thread_pool.write.queue_size/): 配置项作用 # thread_pool.write.queue_size 配置项用于控制写入线程池的队列大小。 当所有写入线程都在忙碌时，新的写入请求会被放入队列等待。 配置项属性 # 配置路径: thread_pool.write.queue_size 数据类型: Integer（整数） 默认值: 10000 是否可选: 是 作用域: NodeScope（节点级别） 动态更新: 是（可以动 … - [仓库异常 (repository_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/repository_exception/): 为什么这个错误发生 # repository_exception 是与快照仓库相关的通用异常，表示在访问或操作快照仓库时发生问题。 这个错误可能由以下原因引起： 仓库不存在：引用的快照仓库未创建 配置错误：仓库配置参数不正确 权限问题：没有访问仓库存储位置的权限 存储不可达：远程存储（S3、HDFS 等）无法访问 空间不足：仓库存储位置空间不足 仓库损坏：仓库元数据损坏 网络问题：与远程仓库的 … - [使用 Easysearch 数据流来简化日志的管理](https://easysearch.cn/knowledge-base/usage/easysearch-data-stream-simplify-log-management/): 在现代企业的 IT 架构中，日志数据往往占据了数据存储的"半壁江山"。从应用程序日志、网关日志到基础设施监控指标，这些时序数据（Time Series Data）具有写入量大、只有追加操作（Append-only）、随时间推移价值递减的特点。 传统的管理方式通常是按天生成索引（如 logs-2023-10-01），但这带来了管理上的复杂性：如何自动化清理旧数据？如何处理某天流量 … - [分片平衡阈值配置](https://easysearch.cn/knowledge-base/easysearch_config/cluster.routing.allocation.balance.threshold/): 配置项作用 # cluster.routing.allocation.balance.threshold 配置项指定触发分片平衡操作的最小权重差异阈值。只有当节点间的权重差异超过此阈值时，才会执行分片迁移以平衡集群。 配置项类型 # 该配置项为动态配置，可以在运行时通过集群设置 API 进行修改。 默认值 # 1.0 是否必需 # 可选配置项（有默认值） 取值范围 # 0.0 ~ … - [删除快照仓库](https://easysearch.cn/knowledge-base/easysearch_api/delete-snapshot-repository/): 此 API 用于删除（注销）快照存储仓库。 API # DELETE /_snapshot/{repository} API 的作用 # 从集群中注销指定的快照存储仓库。 重要说明： 此操作只注销仓库配置，不会删除存储在仓库中的实际数据 仓库中的快照文件仍然保留在存储系统中 如果仓库中仍有快照引用，操作可能失败 API 的参数 # 路由参数 # … - [发现未知的许可证版本，请将所有节点升级到最新的 elasticsearch-license - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unknown-license-version-found-please-upgrade-all-nodes-to-the-latest-elasticsearch-license-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.5 1. 错误异常的基本描述 # 发现未知的许可证版本，请将所有节点升级到最新的 elasticsearch-license 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引 … - [尝试删除不存在的快照 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/attempting-to-remove-non-existent-snapshot-from-repository-data-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.7 1. 错误异常的基本描述 # Attempting to remove non-existent snapshot [{}] from repository data 表示 Elasticsearch 在更新 RepositoryData 时，试图删除一个指定的 snapshot，但当前仓库元数据里根本没有这个 snapshot。源码片段也很清楚： … - [无效值 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/invalid-value-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.8-7.15 1. 错误异常的基本描述 # 无效值 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返回 400、404、409、429、500 … - [无效的聚合器排序路径 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/invalid-aggregator-order-path-this-the-how-to-solve-this-elasticsearch-exception/): 适用版本： 7-7.6 1. 错误异常的基本描述 # 无效的聚合器排序路径 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法解析字段，期望字符串数组但发现 null 值 (expected a string array but found null value instead) - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-field-expected-a-string-array-but-found-null-value-instead-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # 无法解析字段，期望字符串数组但发现 null 值 (expected a string array but found null value instead) 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群 … - [无法解析查询 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/couldn-t-parse-query-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # Couldn't parse query 说明 Elasticsearch 在读取请求中的查询 DSL 时就已经失败了。也就是说，请求还没有真正进入搜索执行阶段，问题先发生在 query 结构、参数格式、字段引用方式或 JSON 内容本身。这类异常和 failed to parse 比较接近，但语义更聚焦在“ … - [映射深度限制 mappingObjectDepthLimit 已超出 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/limit-of-mapping-depth-mappingobjectdepthlimit-has-been-exceeded-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.9-8.9 1. 错误异常的基本描述 # 映射深度限制 mappingObjectDepthLimit 已超出 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 … - [暂不支持 JOIN 查询 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/queries-with-join-are-not-yet-supported-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 暂不支持 JOIN 查询 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [期望单个点但得到列表 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/expected-a-single-points-but-got-a-list-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.2-8.9 1. 错误异常的基本描述 # 期望单个点但得到列表 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [期望字符串但发现了其他类型 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/expected-a-string-but-found-instead-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Expected a string but found [xxx] instead 是 Elasticsearch 在解析请求体或配置文件时抛出的类型不匹配异常，底层通常由 ElasticsearchParseException 触发。当解析器在期望读取一个字符串值的位置，却遇到了对象、数组、数值或布尔值等其他 JSON 类型时，就会抛 … - [期望检查点为long数组但发现了其他类型 – 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/expecting-the-checkpoints-for-to-be-a-long-but-found-instead-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.2-7.5 1. 错误异常的基本描述 # 期望检查点为long数组但发现了其他类型 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [来自未知节点的Leader检查 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/leader-check-from-unknown-node-how-to-solve-this-elasticsearch-exception/): 适用版本： 7-7.4 1. 错误异常的基本描述 # 来自未知节点的Leader检查 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [清理仓库时需要指定 Bucket 选项 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/bucket-option-is-required-for-cleaning-up-repository-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.6-7.17 1. 错误异常的基本描述 # bucket option is required for cleaning up repository 是一个典型的仓库维护参数校验异常。它说明系统正在尝试执行 repository cleanup，但当前传入的仓库定位参数不完整，缺少了最关键的 bucket。对于依赖对象存储的仓库实现来说，不知道 bucket，就无法确定应该清理 … - [禁用脚本编译速率限制配置](https://easysearch.cn/knowledge-base/easysearch_config/script.disable_max_compilations_rate/): 配置项作用 # script.disable_max_compilations_rate 配置项用于控制是否禁用脚本最大编译速率限制。 当设置为 true 时，系统不再对脚本编译的速率进行限制；当设置为 false（默认值）时，启用脚本编译速率限制，以防止资源耗尽。 配置项属性 # 配置路径: script.disable_max_compilations_rate 数据类型: … - [索引分片平衡权重配置](https://easysearch.cn/knowledge-base/easysearch_config/cluster.routing.allocation.balance.index/): 配置项作用 # cluster.routing.allocation.balance.index 配置项定义了分片分配决策中索引级别的平衡权重。此配置控制集群在分配和重新平衡分片时，如何考虑每个索引在各节点上的分布均衡性。 配置项类型 # 该配置项为动态配置，可以在运行时通过集群设置 API 进行修改。 默认值 # 0.55 是否必需 # 可选配置项（有默认值） 取值范围 # 0.0 ~ … - [节点初始主分片恢复数量配置](https://easysearch.cn/knowledge-base/easysearch_config/cluster.routing.allocation.node_initial_primaries_recoveries/): 配置项作用 # cluster.routing.allocation.node_initial_primaries_recoveries 配置项控制每个节点上允许同时进行的初始主分片恢复操作的最大数量。初始主分片恢复是指从本地存储、快照或本地分片恢复主分片的过程，不涉及从其他节点复制数据。 配置项类型 # 该配置项为动态配置，可以在运行时通过集群设置 API 进行修改。 默认值 # 4 是否 … - [角色检索发生一次或多次失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/role-retrieval-had-one-or-more-failures-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 角色检索发生一次或多次失败 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [解析类别定义失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-category-definition-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 解析类别定义失败 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [证书不是X.509格式 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/certificate-is-not-a-x.509-certificate-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.7-8.9 1. 错误异常的基本描述 # 证书不是X.509格式 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [键值对在注解中不被支持 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/keyvalue-pairs-are-not-supported-in-annotations-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 键值对在注解中不被支持 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [cron 配置既不是字符串也不是数组 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-cron-schedule-expected-either-a-cron-string-value-or-an-array-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # could not parse [cron] schedule. expected either a cron string value or an array of cron string values; but found [token] 表示 schedule.cron 字段的顶层 JSON 类型不符合 Watcher 解析器的 … - [Easysearch 为什么一定要“先想好字段类型”](https://easysearch.cn/knowledge-base/usage/easysearch-why-must-define-field-types-first/): 一、动态 Mapping：便捷背后的隐形炸弹 # 动态 Mapping（动态映射）是 Easysearch 的核心特性 —— 无需提前定义字段结构，系统会根据首次写入的数据自动推断字段类型（如字符串映射为 text/keyword、数字映射为 long/integer）。这种 “零配置” 特性适合快速原型验证或日志类半结构化数据，但在生产环境中，其隐藏的风险会直接冲击系统稳定性与业务准确性。 … - [failed to parse licenses, expected field - 解析 licenses 时缺少预期字段](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-licenses-expected-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # failed to parse licenses, expected field 表示 Elasticsearch 在解析 license 相关对象时，没有在当前位置读到解析器预期的字段结构。通常出现在 license 元数据读取或兼容旧/新版本 license 表示形式时。 从保留代码显示，解析器在对象内部期待识别出 license … - [Fetch Shard Started 线程池最大大小配置](https://easysearch.cn/knowledge-base/easysearch_config/thread_pool.fetch_shard_started.max/): 配置项作用 # thread_pool.fetch_shard_started.max 配置项用于控制分片启动状态获取线程池的最大线程数。 这是线程池能够创建的最大线程数量上限，用于限制资源消耗，防止系统过载。 配置项属性 # 配置路径: thread_pool.fetch_shard_started.max 数据类型: Integer（整数） 默认值: 2 × CPU核心数（受限于 2 … - [Master节点离开 – 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/master-left-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.17 1. 错误异常的基本描述 # Master节点离开 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Neither a secret key nor a shared access token was set - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/neither-a-secret-key-nor-a-shared-access-token-was-set-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 这条异常表示 Azure 仓库客户端没有拿到任何可用凭据。源码在构建连接字符串前会检查 sasToken 和 key，若两者都为空，就抛出 SettingsException。 常见现象 # Azure 仓库在初始化或验证时失败。 配置里定义了 client，但没有真正可用的认证信息。 常见于 keystore 未注入、环境变量为空 … - [Phase1 失败 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/phase1-failed-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.2 1. 错误异常的基本描述 # Phase1 失败 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [request does not support [field] - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/request-does-not-support-parser-currentname-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # request does not support [field] 表示解析器已经读到一个字段名，但当前请求对象并不接受这个字段。源码直接使用 parser.currentName() 生成异常内容，所以日志里通常已经点明了具体问题字段。 常见现象 # 请求体是合法 JSON，但仍然返回 400。 返回中明确指向某个字段名。 常见于复 … - [Suggestion 不支持 currentFieldName - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/suggestion-does-not-support-currentfieldname-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Suggestion 不支持 currentFieldName 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Transport TCP 连接超时配置](https://easysearch.cn/knowledge-base/easysearch_config/transport.tcp.connect_timeout/): 配置项作用 # transport.tcp.connect_timeout 配置项用于控制TCP 连接建立的超时时间。 配置项属性 # 配置路径: transport.tcp.connect_timeout 数据类型: TimeValue（时间值） 默认值: 30s（30 秒） 是否可选: 是 作用域: NodeScope（节点级别） 动态更新: 否（需要重启节点生效） 废弃状态: 已废弃， … - [代理必须同时包含 host 和 port - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/proxy-must-contain-port-and-host-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误说明 # Proxy must contain 'port' and 'host' field 是 Elasticsearch 在解析代理（Proxy）配置时抛出的 ElasticsearchParseException。该异常表示 Elasticsearch 在读取代理配置后，发现 host 或 port 字段缺失，无法构造合法的 HttpProxy 对 … - [字段名发现不支持的形状LinearRing - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/field-name-found-an-unsupported-shape-linearring-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.12-8.2 1. 错误异常的基本描述 # 字段名发现不支持的形状LinearRing 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [当传输层启用TLS时无法集群范围更新安全设置 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/secure-settings-cannot-be-updated-cluster-wide-when-tls-for-the-transport-layer-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.7-7.15 1. 错误异常的基本描述 # 当传输层启用TLS时无法集群范围更新安全设置 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [恢复并发文件块数配置](https://easysearch.cn/knowledge-base/easysearch_config/indices.recovery.max_concurrent_file_chunks/): 配置项作用 # indices.recovery.max_concurrent_file_chunks 配置项用于控制在索引恢复过程中，源节点到目标节点可以并发发送的文件块请求数量。 此配置限制同时进行的文件块传输数量，确保恢复目标节点不会缓冲超过限制的文件块，在恢复速度和资源消耗之间取得平衡。 配置项属性 # 配置路径: … - [恢复文件异常 (recover_files_recovery_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/recover_files_recovery_exception/): 为什么这个错误发生 # recover_files_recovery_exception 表示在分片恢复过程中传输文件时失败。恢复文件是分片恢复的关键步骤，需要将索引文件从源节点复制到目标节点。 这个错误可能由以下原因引起： 网络中断：节点间的网络连接在传输过程中中断 磁盘空间不足：目标节点磁盘空间不足 文件损坏：源节点的文件损坏无法读取 传输超时：大文件传输超时 并发限制：达到并发恢复限制 … - [无效的月份日期值：期望字符串或数字值但找到了其他值 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/invalid-month-day-value-expected-a-string-or-a-number-value-but-found-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 无效的月份日期值：期望字符串或数字值但找到了其他值 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返 … - [无效的身份验证请求查询字符串参数为零 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/invalid-authentication-request-query-string-zero-parameters-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.7-8.9 1. 错误异常的基本描述 # 无效的身份验证请求查询字符串参数为零 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法解析仓库未知类型 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-repository-unknown-type-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # failed to parse repository [...] unknown type 表示 Elasticsearch 在解析仓库定义时，发现 type 字段本身不是合法的字符串值，或者当前解析位置上的 token 与仓库类型应有的格式不匹配。它比“missing repository type”更进一步，说明字段可能存在，但格式 … - [未知的参数 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unknown-parameter-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.13 1. 错误异常的基本描述 # 未知的参数 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [未能续订同步提交 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-renew-sync-commit-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.17 1. 错误异常的基本描述 # 未能续订同步提交 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [查询快照信息](https://easysearch.cn/knowledge-base/easysearch_api/get-snapshot-info/): 获取指定快照的详细信息，或查询仓库中的所有快照。 API 格式 # GET /_snapshot/{repository}/{snapshot} GET /_snapshot/{repository} API 作用 # 该 API 用于检索快照信息： 获取特定快照的详细信息和状态 列出仓库中的所有快照 检查快照的完整性和可用性 查看快照包含的索引和元数据 API 参数 # 路径参数 # … - [查询节点 nodeIds 失败 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-query-nodes-nodeids-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.9-8.9 1. 错误异常的基本描述 # 查询节点 nodeIds 失败 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [此 JDK 不支持线程 CPU 时间 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/thread-cpu-time-is-not-supported-on-this-jdk-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 此 JDK 不支持线程 CPU 时间 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [等待动态映射更新超时 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/timed-out-while-waiting-for-a-dynamic-mapping-update-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 等待动态映射更新超时 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [等待映射更新超时 timeout timeout - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/timed-out-waiting-for-mapping-updates-timeout-timeout-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.16-8.9 1. 错误异常的基本描述 # 等待映射更新超时 timeout timeout 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [索引 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/index-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.2-7.15 1. 错误异常的基本描述 # 索引 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返回 400、404、409、429、500 … - [索引状态管理受限索引模式配置](https://easysearch.cn/knowledge-base/easysearch_config/index_state_management.restricted_index_pattern/): 配置项作用 # index_state_management.restricted_index_pattern 配置项用于定义不允许被索引状态管理（ISM）策略管理的索引模式。 配置项属性 # 配置路径: index_state_management.restricted_index_pattern 数据类型: String（字符串，正则表达式模式） 默认值: … - [解析 multi get 请求失败：未知字段 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-multi-get-request-unknown-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # failed to parse multi get request. unknown field 表示 Elasticsearch 在解析 Multi Get（mget）请求时，发现请求体中包含了该接口不支持的未知字段，导致请求在解析阶段直接失败。Multi Get 接口允许一次性根据多个文档 ID 批量获取文档，其请求结构有严格的字段 … - [进程监控刷新间隔配置](https://easysearch.cn/knowledge-base/easysearch_config/monitor.process.refresh_interval/): 配置项作用 # monitor.process.refresh_interval 配置项用于控制进程监控服务收集和刷新进程统计信息的间隔时间。 此配置决定了 ProcessService 多久刷新一次进程级别指标，包括打开的文件描述符、CPU 使用率、内存使用等。 配置项属性 # 配置路径: monitor.process.refresh_interval 数据类型: TimeValue（时 … - [金融风控实时查询平台：Easysearch 在反欺诈场景的应用](https://easysearch.cn/knowledge-base/best/easysearch-finance-risk-control-fraud-detection/): 在金融支付与信贷领域，**“200毫秒”**往往是生死线。 当用户刷卡消费或发起贷款申请时，风控系统必须在眨眼之间完成成百上千条规则的计算：该用户是否在黑名单？这笔交易的地理位置是否异常？过去一小时内是否有高频小额试探？ 一旦超时，要么为了用户体验放行（导致资损风险），要么为了安全拦截（导致客诉）。在这场与黑产的赛跑中，底层数据引擎的查询性能决定了胜负。 本文将探讨如何利用 INFINI … - [集群状态提交超时配置](https://easysearch.cn/knowledge-base/easysearch_config/discovery.zen.commit_timeout/): 配置项作用 # discovery.zen.commit_timeout 配置项用于设置主节点等待其他主节点确认（ACK）集群状态提交的超时时间。 当主节点发布集群状态变更后，需要等待足够数量的主节点确认才能提交。如果在此时间内未收到足够的确认，变更将被拒绝。 配置项属性 # 配置路径: discovery.zen.commit_timeout 数据类型: TimeValue（时间值） 默认 … - [非法字段 multiFieldName：fields 内部只能指定字段——如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/illegal-field-multifieldname-only-fields-can-be-specified-inside-fields-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 非法字段 multiFieldName：fields 内部只能指定字段— 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现 … - [AUTO_CREATE_INDEX_SETTING getKey autoCreate doesn't match - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/auto-create-index-setting-getkey-autocreate-doesn-t-match-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.16-8.9 1. 错误异常的基本描述 # AUTO_CREATE_INDEX_SETTING getKey autoCreate doesn't match 表示 Elasticsearch 在尝试自动创建索引时，发现请求中的索引名称与集群配置的 action.auto_create_index 模式规则不匹配，从而拒绝创建索引并抛出异常。 该异常通常发生在写入或索引操作触发 … - [blob already exists while finalizing snapshot - 快照收尾时 Blob 已存在如何解决](https://easysearch.cn/knowledge-base/elasticsearch_error/blob-already-exists-while-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.4 1. 错误异常的基本描述 # Blob already exists while finalizing snapshot; assume the snapshot has already been saved 表示 Elasticsearch 在执行快照的 finalize（收尾）阶段时，尝试写入索引代际信息（index generation blob）到快照仓库， … - [Easysearch 在站内搜索、电商检索等业务场景中的应用](https://easysearch.cn/knowledge-base/best/easysearch-search-applications-site-ecommerce/): 提到 INFINI Easysearch，大多数人的第一反应是：“哦，那个存日志很省钱的数据库。” 确实，Easysearch 凭借 ZSTD 压缩和高吞吐写入，在日志分析场景大杀四方。但不要忘了，它的内核是 Apache Lucene——这个星球上最强大的全文检索库。这意味着，Easysearch 天生就是为了解决**“搜索”**问题而生的。 从企业门户的站内搜索，到千万级商品的电商检 … - [Easysearch 索引生命周期管理（ILM）：自动处理冷热数据](https://easysearch.cn/knowledge-base/usage/easysearch-index-lifecycle-management-hot-cold-data/): 随着时间推移，日志、监控指标等时序数据的价值密度会逐渐降低。一周前的数据需要毫秒级查询，而一年前的数据可能只需偶尔归档检索。如果在昂贵的 NVMe SSD 上存储所有历史数据，成本将难以承受。 索引生命周期管理（ILM） 是解决这一矛盾的核心机制。结合 INFINI Easysearch 强大的 ZSTD 压缩与分层存储能力，我们可以构建一套自动化的数据流转体系：让热数据“跑”在高性能节点，让冷数 … - [Fields 必须是对象但得到了其他类型 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/fields-must-be-an-object-got-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.15-7.15 1. 错误异常的基本描述 # Fields 必须是对象但得到了其他类型 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Header不能通过concreteSetting getKey name覆盖 – 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/header-cannot-be-overwritten-via-concretesetting-getkey-name-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.17 1. 错误异常的基本描述 # Header不能通过concreteSetting getKey name覆盖 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 … - [Hunspell 词典延迟加载配置](https://easysearch.cn/knowledge-base/easysearch_config/indices.analysis.hunspell.dictionary.lazy/): 配置项作用 # indices.analysis.hunspell.dictionary.lazy 配置项控制 Hunspell 词典的加载策略。启用延迟加载后，词典将在首次使用时才加载，而不是在节点启动时加载。 默认值 # false（立即加载） 配置类型 # 节点级配置 取值范围 # true：延迟加载（首次使用时加载） false：立即加载（启动时加载） 配置格式 # # 启用 … - [Ingest Grok 看门狗检查间隔配置](https://easysearch.cn/knowledge-base/easysearch_config/ingest.grok.watchdog.interval/): 配置项作用 # ingest.grok.watchdog.interval 配置项控制 Grok 看门狗检查执行时间的间隔。 默认值 # 1s 配置类型 # 静态配置 配置格式 # # 默认配置 ingest.grok.watchdog.interval: 1s # 增加检查间隔 ingest.grok.watchdog.interval: 5s # … - [Jira 账户配置中的 URL 设置无效 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/invalid-jira-name-account-settings-invalid-url-setting-setting-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # 这个异常说明 Jira account 的 URL 设置存在，但值本身不合法，无法通过 URI 解析或构造。它和“缺少必填设置”不同，表示配置有值，但格式错误。 典型报错： invalid jira [ops_jira] account settings. invalid [url] setting 2. 为什么会发生这个错误 # … - [Parameter coordinates is not supported for type – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/parameter-coordinates-is-not-supported-for-type-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.2-8.9 1. 错误异常的基本描述 # Parameter coordinates is not supported for type 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引 … - [RecoveryStatus 被使用但引用计数为 0，可能是 incRef/decRef 不匹配 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/recoverystatus-is-used-but-it-s-refcount-is-0-probably-a-mismatch-between-incref-decref-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # RecoveryStatus 被使用但引用计数为 0，可能是 incRef/decRef 不匹配 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下 … - [Rollup 搜索所有任务配置](https://easysearch.cn/knowledge-base/easysearch_config/rollup.search.search_all_jobs/): 配置项作用 # rollup.search.search_all_jobs 配置项用于控制搜索时是否包含所有的 Rollup 任务。 当设置为 true 时，搜索会包含所有 Rollup 任务；当设置为 false 时，搜索只会根据字段映射匹配相关的 Rollup 任务。 配置项属性 # 配置路径: rollup.search.search_all_jobs 数据类型: Boolean（布尔 … - [Shard必须具有有效的translog UUID – 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/shard-must-have-a-valid-translog-uuid-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.7-8.9 1. 错误异常的基本描述 # Shard必须具有有效的translog UUID 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可 … - [Span or 子句必须是 span 查询类型 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/span-or-clauses-must-be-of-type-span-query-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Span or 子句必须是 span 查询类型 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Translog header corrupted – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/translog-header-corrupted-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Translog header corrupted 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可 … - [分片未处于主分片模式——如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/shard-is-not-in-primary-mode-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 分片未处于主分片模式— 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [分片重新平衡启用配置](https://easysearch.cn/knowledge-base/easysearch_config/cluster.routing.rebalance.enable/): 配置项作用 # cluster.routing.rebalance.enable 配置项控制集群中分片的重新平衡（Rebalancing）行为。重新平衡是指集群自动将分片从负载较高的节点移动到负载较低的节点，以实现集群负载的均匀分布。 配置项类型 # 该配置项为动态配置，可以在运行时通过集群设置 API 进行修改。 默认值 # all（允许所有分片重新平衡） 是否必需 # 可选配置项（有默 … - [在描述符中找到多个绑定位置 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/found-multiple-locations-for-binding-in-descriptor-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # 在描述符中找到多个绑定位置 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [处理集群事件超时 (process_cluster_event_timeout_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/process_cluster_event_timeout_exception/): 为什么这个错误发生 # process_cluster_event_timeout_exception 表示集群在规定时间内无法处理完成某个集群级别的元数据更新事件。集群元数据包括索引、分片、映射、索引模板等配置信息，这些信息需要在所有节点间保持一致。 这个错误可能由以下原因引起： 主节点负载过高：主节点正在处理大量元数据更新，CPU 或 I/O 负载过高 节点故障：部分节点无法响应主节点的状 … - [字段类型不支持超过2维 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/field-type-does-not-accept-2-dimensions-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.8-7.15 1. 错误异常的基本描述 # 字段类型不支持超过2维 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [投票配置排除](https://easysearch.cn/knowledge-base/easysearch_api/vote-config-exclusion/): 管理集群投票配置排除列表，用于添加或清除被排除的节点，使其不再参与集群的投票和领导选举。 API # POST /_cluster/voting_config_exclusions DELETE /_cluster/voting_config_exclusions API 的作用 # POST /_cluster/voting_config_exclusions # 添加节点到集群投票配置排 … - [授权类型不受支持 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/the-grant-type-is-not-supported-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.7-8.9 1. 错误异常的基本描述 # 授权类型不受支持 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无效策略 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/invalid-policy-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # 无效策略 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法启动 Data Frame Transform 任务，因为状态不允许 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-start-task-for-data-frame-transform-because-state-was-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.2-7.4 1. 错误异常的基本描述 # Cannot start task for data frame transform [xxx], because state was [yyy] 表示 Elasticsearch 在尝试启动一个 Data Frame Transform 任务时，底层 Indexer 返回的状态不在允许的运行状态集合中，因此任务被直接拒绝启动。 该异常 … - [无法构造SAML重定向 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-construct-saml-redirect-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 无法构造SAML重定向 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法解析监视器的 Action：字段解析失败，必须是字符串值 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-action-for-watch-failed-to-parse-must-be-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # 当 Watcher 解析某个 action 定义时，如果期望读取字符串字段，却实际遇到了布尔、数字、数组或对象，就会抛出这一类异常。当前页附带的源码片段对应的是 index action 中的动态索引名时区字段： "dynamic_name_timezone": "UTC" 如果把它写成下面这样，就会直 … - [检索 DEK dekId 时发生意外异常 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unexpected-exception-retrieving-dek-dekid-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.12-8.6 1. 错误异常的基本描述 # Unexpected exception retrieving DEK [dekId] 表示 Elasticsearch 在读取仓库内部保存的 DEK 时，捕获到了一个既不是 IOException、也不是 ElasticsearchException 的异常，于是将其包装成 RepositoryException 抛出。 … - [等待投票配置排除超时 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/timed-out-waiting-for-voting-config-exclusions-how-to-solve-this-elasticsearch-exception/): 适用版本： 7-7.15 1. 错误异常的基本描述 # 等待投票配置排除超时 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [类型为 typeName 的字段 name 不可搜索 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/field-name-of-type-typename-is-not-searchable-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.11-8.9 1. 错误异常的基本描述 # 类型为 typeName 的字段 name 不可搜索 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可 … - [索引副本数配置](https://easysearch.cn/knowledge-base/easysearch_config/config_index.number_of_replicas/): 配置项作用 # index.number_of_replicas 配置项指定每个主分片的副本数量。副本分片是主分片的完整复制，提供数据冗余、高可用性和读取吞吐量的扩展。 配置项类型 # 该配置项为动态配置，可以在运行时通过索引设置 API 进行修改。 默认值 # 1（每个主分片有 1 个副本） 是否必需 # 可选配置项（有默认值） 取值范围 # 0 ~ 正整数 配置格式 # # 创建索 … - [节点级限流令牌补充间隔配置](https://easysearch.cn/knowledge-base/easysearch_config/cluster.throttle.node.write.interval/): 配置项作用 # 设置节点级限流令牌桶的令牌补充间隔时间（秒）。 默认值 # 1 配置格式 # # 每秒补充一次令牌（默认） cluster.throttle.node.write.interval: 1 # 每 2 秒补充一次 cluster.throttle.node.write.interval: 2 - [解析为 Double 类型失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-as-a-double-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 解析为 Double 类型失败 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 典型报错与异常栈 # … - [运行时字段 fieldName 声明的类型 type 没有处理器 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/no-handler-for-type-type-declared-on-runtime-field-fieldname-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.16-8.9 1. 错误异常的基本描述 # 运行时字段 fieldName 声明的类型 type 没有处理器 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [AES 包装 DEK 失败 dekId - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failure-to-aes-wrap-the-dek-dekid-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.12-8.6 1. 错误异常的基本描述 # Failure to AES wrap the DEK [dekId] 表示 Elasticsearch 在加密快照仓库中准备写入 DEK（数据加密密钥）时，尝试使用 KEK（密钥加密密钥）对 DEK 做 AES 包装失败。 从源码看，这个异常只会在 GeneralSecurityException 被捕获后抛出， … - [analyzer on completion field must be set when search_analyzer is set - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/analyzer-on-completion-field-name-must-be-set-when-search-analyzer-is-set-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11+ 1. 错误异常的基本描述 # analyzer on completion field [name] must be set when search_analyzer is set 是 Elasticsearch 在解析 completion 字段（自动补全字段）的映射配置时抛出的参数验证错误。当你在 completion … - [assignment already exists - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/assignment-already-exists-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.3-8.9（机器学习功能） 1. 错误异常的基本描述 # assignment already exists 是 Elasticsearch 在部署或重新分配机器学习（Machine Learning）模型时抛出的异常，完整异常类通常为 ResourceAlreadyExistsException。该错误表示当前集群中已经存在一个与目标 deploymentId 对应的模型分配 … - [Hunspell字典%s的affix文件过多——如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/too-many-affix-files-exist-for-hunspell-dictionary-s-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Hunspell字典%s的affix文件过多— 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [slice 不能脱离 scroll 使用 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/slice-cannot-be-used-outside-of-a-scroll-context-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.14 1. 错误异常的基本描述 # slice cannot be used outside of a scroll context 是 Elasticsearch 在查询解析阶段直接抛出的异常，含义非常明确：当请求体中包含 slice 参数，但查询并未在 scroll 上下文中执行时，Elasticsearch 会拒绝该请求。 常见现象 # … - [Warmer 线程池最大大小配置](https://easysearch.cn/knowledge-base/easysearch_config/thread_pool.warmer.max/): 配置项作用 # thread_pool.warmer.max 配置项用于控制索引预热线程池的最大线程数。 配置项属性 # 配置路径: thread_pool.warmer.max 数据类型: Integer（整数） 默认值: min(5, (CPU核心数 + 1) / 2) 是否可选: 是 作用域: NodeScope（节点级别） 动态更新: 是（可以动态更新，无需重启） 配置建议 # … - [watch 的 HTTP input 缺少 request 字段 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-input-for-watch-missing-require-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.x 1. 错误异常的基本描述 # could not parse [http] input for watch [<id>]. missing require [request] field 是 Elasticsearch Watcher 在解析 HTTP input 配置时抛出的解析异常。该错误表示 Watcher 在解析 input.http 配置段时， … - [元数据不能超过5个条目但获得meta size在字段上 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/meta-can-t-have-more-than-5-entries-but-got-meta-size-on-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.6-7.15 1. 错误异常的基本描述 # 元数据不能超过5个条目但获得meta size在字段上 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口 … - [写入提交点失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-write-commit-point-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 写入提交点失败 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [分片启动获取线程池配置](https://easysearch.cn/knowledge-base/easysearch_config/thread_pool.fetch_shard_started/): 配置项作用 # thread_pool.fetch_shard_started 相关配置项控制用于执行分片启动后获取操作的线程池。当分片启动后需要从其他节点获取数据时使用此线程池。该线程池采用伸缩线程池类型。 配置项类型 # 该配置项为静态配置，需要在启动时设置，修改后需要重启节点才能生效。 默认值 # thread_pool.fetch_shard_started.core: 1 … - [分片失败 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/shard-failures-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 分片失败 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [分片已关闭 (index_shard_closed_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/index_shard_closed_exception/): 为什么这个错误发生 # index_shard_closed_exception 表示尝试对已关闭的分片执行操作。 如何修复 # 1. 检查分片状态 # GET /_cat/shards?v 2. 重新打开分片 # POST /<index>/_open 3. 触发分片恢复 # POST /_cluster/reroute?retry_failed=true 预防措施 # … - [初始配置中发现节点不足无法形成法定人数——如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/not-enough-nodes-discovered-to-form-a-quorum-in-the-initial-configuration-how-to-solve-this-elasticsearch-exception/): 适用版本： 7-7.15 1. 错误异常的基本描述 # 初始配置中发现节点不足无法形成法定人数— 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [加载监视器时出现部分响应 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/partial-response-while-loading-watches-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 加载监视器时出现部分响应 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [命令缺少node参数 – 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/command-missing-the-node-parameter-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 命令缺少node参数 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [如何将 Easysearch 与可视化监控系统集成？](https://easysearch.cn/knowledge-base/best/easysearch-visualization-monitoring-system-integration/): 如果说 INFINI Easysearch 是一台性能强悍的法拉利引擎（数据底座），那么 **INFINI Console **就是为其量身定制的数字化仪表盘和驾驶舱。 在构建基于 Easysearch 的搜索与分析平台时，很多用户会惯性地寻找 Kibana 或 Grafana。但在 Easysearch 的生态中，INFINI Console 才是官方推荐的、能力最全面的可视化监控与管控平台。 … - [字段数据断路器开销系数配置](https://easysearch.cn/knowledge-base/easysearch_config/indices.breaker.fielddata.overhead/): 配置项作用 # indices.breaker.fielddata.overhead 配置项控制字段数据断路器的内存开销估算常数，用于更准确地计算字段数据的内存使用。 默认值 # 1.03 配置类型 # 动态配置 取值范围 # 正数（通常 1.0 ~ 2.0） 配置格式 # # 默认配置 indices.breaker.fielddata.overhead: 1.03 # … - [字段类型不接受多字段 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/field-type-does-not-accept-multi-fields-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.8-7.8 1. 错误异常的基本描述 # 字段类型不接受多字段 表示某个字段的 mapping 里声明了 fields 子字段，但该父字段类型本身并不支持 multi-fields。源码片段里已经很明确，只要解析到 multi-fields，而当前字段类型不接受，就会直接抛出 ElasticsearchParseException。 常见现象 # 创建索引、 … - [推理过程错误 errorMessage – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/error-in-inference-process-errormessage-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.3-8.9 1. 错误异常的基本描述 # 推理过程错误 errorMessage 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [搜索结果不对？你可能忽略了 Easysearch 的评分机制](https://easysearch.cn/knowledge-base/usage/easysearch-scoring-mechanism-guide/): “为什么完全匹配的文档排在后面？” “为什么这篇明明只有几个关键词的文章，分数却比那篇长文还高？” “为什么我在开发环境和生产环境搜出来的排序不一样？” 这些是每一个 Easysearch (Elasticsearch) 开发者在职业生涯中都会遇到的“灵魂拷问”。当业务方质疑搜索结果“不对”时，很多人的第一反应是“是不是有 Bug？”。 其实，99% 的情况下，这并非 Bug， … - [无法删除指定ID的过滤器 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-delete-filter-with-id-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # 无法删除指定ID的过滤器 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法将设置值解析为字节大小 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-setting-with-value-as-a-size-in-bytes-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # 无法将设置值解析为字节大小 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法清理路径 path - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unable-to-clean-up-path-path-how-to-solve-this-elasticsearch-exception/): 适用版本： 7-8.9 1. 错误异常的基本描述 # 无法清理路径 path 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法解析字段值，无法将其作为地址 (could not parse field with value as address) - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-field-field-with-value-text-as-address-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # 无法解析字段值，无法将其作为地址 (could not parse field with value as address) 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义， … - [无法解析监视器执行请求，出现未预期的对象字段（Could not parse watch execution request. unexpected object field）- 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-watch-execution-request-unexpected-object-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.x 1. 错误异常的基本描述 # could not parse watch execution request. unexpected object field [...] 表示 Execute Watch 请求中出现了一个对象字段，但这个对象字段不允许直接出现在当前层级。 这类问题在 Watcher 中很常见，因为执行请求和 watch 本身的定义结构不同。很多人会 … - [日志级别配置](https://easysearch.cn/knowledge-base/easysearch_config/logger.level/): 配置项作用 # logger.level 配置项用于控制Easysearch 系统中所有日志记录器的默认日志级别。 当没有为特定日志记录器设置级别时，所有日志将使用这个默认级别。此配置影响日志系统的基础日志级别，决定哪些级别的日志信息会被输出。 配置项属性 # 配置路径: logger.level 数据类型: Level（Log4j2 日志级别枚举） 默认值: INFO 可选值: … - [期望使用Bearer但收到了无效的访问令牌类型——如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/invalid-access-token-type-while-bearer-was-expected-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.2-7.15 1. 错误异常的基本描述 # 期望使用Bearer但收到了无效的访问令牌类型— 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [未知参数 incremental_file_count - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unknown-parameter-incremental-file-count-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 未知参数 incremental_file_count 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接 … - [由于watches索引未分配导致无法管理集群告警 – 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-manage-cluster-alerts-because-watches-index-is-not-allocated-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.11-8.9 1. 错误异常的基本描述 # 由于watches索引未分配导致无法管理集群告警 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可 … - [索引缓存清理间隔配置](https://easysearch.cn/knowledge-base/easysearch_config/indices.cache.cleanup_interval/): 配置项作用 # indices.cache.cleanup_interval 配置项控制清理已关闭索引缓存的间隔时间。系统定期清理已关闭索引的缓存资源，包括内存中的索引元数据和文件句柄等。 配置项类型 # 该配置项为静态配置，需要在启动时设置，修改后需要重启节点才能生效。 默认值 # 1m 是否必需 # 可选配置项（有默认值） 取值范围 # 0 ~ 正无穷 配置格式 # # … - [节点关闭 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/node-closed-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.8-8.9 1. 错误异常的基本描述 # 节点关闭 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [获取节点统计信息](https://easysearch.cn/knowledge-base/easysearch_api/get-node-stats/): 获取集群中节点的统计信息，包括操作系统、JVM、索引、网络等方面的性能指标和资源使用情况。 API # GET /_cluster/nodes/stats GET /_nodes/stats GET /_nodes/{nodeId}/stats GET /_nodes/stats/{metric} GET /_nodes/{nodeId}/stats/{metric} GET … - [跟随者轮询间隔配置](https://easysearch.cn/knowledge-base/easysearch_config/replication.follower.poll_interval/): 配置项作用 # replication.follower.poll_interval 配置项用于控制跟随者轮询 Leader 集群检查新操作的间隔时间。 当 Follower 已经追上 Leader 的操作（没有新的操作需要复制）时，系统会等待此间隔后再次检查。此配置直接影响复制延迟和 Leader 集群的负载。 配置项属性 # 配置路径: … - [迁移角色 roleName 失败 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-migrate-role-rolename-with-body-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.17 1. 错误异常的基本描述 # 迁移角色 roleName 失败 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [预期的映射器解析失败，实际得到 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/expected-mapper-parsing-failures-got-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 预期的映射器解析失败，实际得到 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Allocation命令格式错误——如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/allocation-command-is-malformed-got-instead-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Allocation命令格式错误— 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Boosting 查询不支持 currentFieldName – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/boosting-query-does-not-support-currentfieldname-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.17 1. 错误异常的基本描述 # [boosting] query does not support [currentFieldName] 是 Elasticsearch 在解析 boosting 查询 DSL 时抛出的语法错误。该异常属于 parsing_exception，意味着请求体中的 boosting 查询结构包含了 Elasticsearch 无法识别的顶 … - [concurrent modification of the index-N file; expected current generation [...] - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/concurrent-modification-of-the-index-n-file-expected-current-generation-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.13 1. 错误异常的基本描述 # index-N 是快照仓库的核心元数据文件，记录了仓库当前代际和快照视图。Elasticsearch 在读取仓库数据时，会先确认当前应加载的 generation 是否仍然等于自己预期的 repositoryStateId。如果不一致，就说明 index-N 在当前流程之外被并发改写了，于是抛出 concurrent … - [ConfigKey 无效主机 host - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/configkey-invalid-host-host-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.4 1. 错误异常的基本描述 # ConfigKey 无效主机 host 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [CONTENT TYPE类型的字段名称 – 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/field-name-of-type-content-type-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.6-7.9 1. 错误异常的基本描述 # CONTENT TYPE类型的字段名称 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [CORS 凭证允许配置](https://easysearch.cn/knowledge-base/easysearch_config/http.cors.allow-credentials/): 配置项作用 # http.cors.allow-credentials 配置项用于控制在跨域资源共享（CORS）响应中是否包含 Access-Control-Allow-Credentials 头。 当启用此配置时，浏览器可以在跨域请求中发送包含凭证的请求，如 Cookies、HTTP 认证信息或客户端 SSL 证书。 配置项属性 # 配置路径: … - [could not parse jira response unexpected field - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-jira-response-unexpected-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # could not parse jira response. unexpected field [field] 是 Elasticsearch Watcher 在与 Jira 集成时抛出的解析异常。当 Watcher 的 Jira action 收到 Jira API 的响应后，如果响应体中包含当前解析器未定义的字段，就会触发此错误。 … - [could not parse schedule expected a schedule type field but found instead - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-schedule-expected-a-schedule-type-field-but-found-instead-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # could not parse schedule. expected a schedule type field; but found [token] instead 是 Elasticsearch Watcher 在解析 schedule（调度）配置时抛出的异常。当 schedule 对象内部没有合法的调度类型字段（ … - [Easysearch Mapping：一次定义错误，后面全是坑](https://easysearch.cn/knowledge-base/usage/easysearch-mapping-one-mistake-all-troubles/): 一、Mapping 的本质：Easysearch 的 “数据说明书” # Mapping 是 Easysearch 索引的核心元数据，定义了字段的数据类型、分词策略、索引行为等关键规则，相当于关系型数据库的表结构（Schema）。没有 Mapping，Easysearch 无法判断字段是文本还是数值、是否需要分词，进而无法实现高效检索。例如： 文本字段（text）需配置分词器实现全文检索 数值 … - [Easysearch 映射（Mapping）入门：如何正确定义数据结构](https://easysearch.cn/knowledge-base/basic/easysearch-mapping-introduction/): 在使用 Easysearch 的过程中，很多开发者都会遇到这样的问题： 为什么同样的数据，搜索结果不一致？ 为什么字段不能排序或聚合？ 为什么写入一段时间后，索引变得越来越“难维护”？ 这些问题，大多都与一个核心概念有关——映射（Mapping）。 本文将从入门视角出发，系统介绍 Easysearch 中 Mapping 的作用、字段数据类型、动态映射机制，以及如何查看和修改映射，帮助你在一开始就 … - [graph vertices 定义缺少 field 名称 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/missing-field-name-in-graph-vertices-definition-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Missing field name in graph vertices definition 是 Elasticsearch Graph API 在解析 vertices 定义时抛出的 parse_exception 类型异常。该错误表示 Graph Explore 请求中某个 vertices 对象缺少必需的 field 属性， … - [Has parent 查询不支持 currentFieldName - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/has-parent-query-does-not-support-currentfieldname-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.16-8.9 1. 错误异常的基本描述 # Has parent 查询不支持 currentFieldName 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 … - [JobId 搜索过期快照失败 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/jobid-search-for-expired-snapshots-failed-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.9 1. 错误异常的基本描述 # [jobId] Search for expired snapshots failed 是上一条通用异常的 job 级具体化版本。它明确告诉你：某个具体的 ML job 在搜索过期 model snapshot 时失败，而不是整个 retention 过程都无差别出错。源码里异常文案直接带上 jobId， … - [NAME 分析器未找到 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/name-analyzer-analyzer-not-found-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # NAME 分析器未找到 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [System Read 线程池大小配置](https://easysearch.cn/knowledge-base/easysearch_config/thread_pool.system_read.size/): 配置项作用 # thread_pool.system_read.size 配置项用于控制系统读取线程池的线程数量。 配置项属性 # 配置路径: thread_pool.system_read.size 数据类型: Integer（整数） 默认值: (CPU核心数 + 1) / 2，范围 1-5 是否可选: 是 作用域: NodeScope（节点级别） 动态更新: 否（需要重启节点生效） 配 … - [System Write 线程池队列大小配置](https://easysearch.cn/knowledge-base/easysearch_config/thread_pool.system_write.queue_size/): 配置项作用 # thread_pool.system_write.queue_size 配置项用于控制系统写入线程池的队列大小。 配置项属性 # 配置路径: thread_pool.system_write.queue_size 数据类型: Integer（整数） 默认值: 1000 是否可选: 是 作用域: NodeScope（节点级别） 动态更新: 否（需要重启节点生效） 配置建议 # … - [上下文未认证 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/context-is-not-authenticated-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.8-8.9 1. 错误异常的基本描述 # 上下文未认证 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返回 400、404、409、429、500 … - [任务ID已存在——如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/task-with-id-taskid-already-exist-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 任务ID已存在— 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [分片级限流处理动作配置](https://easysearch.cn/knowledge-base/easysearch_config/cluster.throttle.shard.write.action/): 配置项作用 # 当分片级限流触发时的处理动作。 默认值 # DROP 取值范围 # DROP：丢弃超出的请求 THROTTLE：延迟处理 配置格式 # # 丢弃超出的请求（默认） cluster.throttle.shard.write.action: DROP # 延迟处理 cluster.throttle.shard.write.action: THROTTLE - [搜索默认保持时间配置](https://easysearch.cn/knowledge-base/easysearch_config/search.default_keep_alive/): 配置项作用 # search.default_keep_alive 配置项指定搜索上下文（Scroll Context）的默认保持时间。当执行滚动查询时，此配置决定搜索结果在服务器上保持有效的时长。 配置项类型 # 该配置项为动态配置，可以在运行时通过集群设置 API 进行修改。 默认值 # 5m（5分钟） 是否必需 # 可选配置项（有默认值） 取值范围 # 1m ~ … - [收集管道信息时发生意外失败](https://easysearch.cn/knowledge-base/elasticsearch_error/unexpected-failure-gathering-pipeline-information-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.6-8.2 1. 错误异常的基本描述 # 收集管道信息时发生意外失败 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [文档映射类型名称不能以下划线开头 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/document-mapping-type-name-can-t-start-with-found-mappingtype-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.17 1. 错误异常的基本描述 # 文档映射类型名称不能以下划线开头 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无效的时间小时值 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/invalid-time-hour-value-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 无效的时间小时值 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无效的聚合名称 – 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/invalid-aggregation-name-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # 无效的聚合名称 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法解析内部脚本定义 (Could not parse inner script definition) - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-inner-script-definition-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 无法解析内部脚本定义 (Could not parse inner script definition) 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上 … - [无法解析百分比显著性启发式算法，预期为空对象 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-percentage-significance-heuristic-expected-an-empty-object-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # 无法解析百分比显著性启发式算法，预期为空对象 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法解析监视器条件，定义无效，缺少条件类型字段（Could not parse condition for watch. invalid definition. expected a field indicating the condition type）- 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-condition-for-watch-invalid-definition-expected-a-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.x 1. 错误异常的基本描述 # could not parse condition for watch [...]. invalid definition. expected a field indicating the condition type; but found [...] 表示 Watcher 在解析 condition 顶层定义时，原本应该先读到条件类型 … - [构建 Clear Scroll 请求体失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-build-clear-scroll-entity-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # failed to build clear scroll entity 表示 Elasticsearch 客户端在发送 clear scroll 请求之前，构建 JSON 请求体时发生了序列化失败。这个错误不是 scroll 上下文清理失败，而是请求尚未到达 Elasticsearch 服务端就在客户端侧中断了。 常见现象 # 应用 … - [查询分段信息（Cat格式）](https://easysearch.cn/knowledge-base/easysearch_api/get-segment-info-cat-format/): 以紧凑的表格形式返回索引的 Lucene 分段信息。 API 格式 # GET /_cat/segments GET /_cat/segments/{index} API 作用 # 该 API 以表格形式返回 Lucene 分段信息： 显示所有索引或指定索引的分段 显示分段的文档数量和大小 显示分段的内存使用情况 显示分段是否可搜索和已提交 API 参数 # 路径参数 # 参数 … - [父任务被取消，不应启动任何子任务 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/the-parent-task-was-cancelled-shouldn-t-start-any-child-tasks-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.8-7.14 1. 错误异常的基本描述 # 父任务被取消，不应启动任何子任务 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [索引分片正在恢复异常 (index_shard_recovering_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/index_shard_recovering_exception/): 为什么这个错误发生 # index_shard_recovering_exception 表示尝试对正在进行恢复（recovering）的分片执行不允许的操作。当分片处于恢复状态时，某些操作（如再次启动恢复）会被拒绝。 这个错误可能由以下原因引起： 分片正在恢复：分片当前正在执行恢复操作 并发恢复请求：同时发起了多个恢复请求 分片处于恢复后状态：分片处于 POST_RECOVERY 状态 节点 … - [索引恢复失败 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-recover-index-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 索引恢复失败 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [节点加入集群超时配置](https://easysearch.cn/knowledge-base/easysearch_config/cluster.join.timeout/): 配置项作用 # cluster.join.timeout 配置项控制节点尝试加入集群时的超时时间。当节点向主节点发送加入请求后，如果在指定时间内未收到响应，则认为本次加入尝试失败。 配置项类型 # 该配置项为静态配置，需要在启动时设置，修改后需要重启节点才能生效。 默认值 # 60s 是否必需 # 可选配置项（有默认值） 取值范围 # 1ms ~ 正无穷 配置格式 # # … - [data attachment 出现未预期字段 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-data-attachment-unexpected-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # could not parse data attachment. unexpected field [field_name] 是 Elasticsearch 在解析 data attachment 配置时抛出的异常，表示当前配置中出现了一个解析器无法识别的字段名。该异常属于 ElasticsearchParseException，通常出 … - [Easysearch 嵌套与反向嵌套聚合：看完就够了](https://easysearch.cn/knowledge-base/usage/easysearch-nested-and-reverse-nested-aggregations/): 在复杂数据模型中，常常会遇到文档中包含数组对象的场景，例如订单中包含多个商品、日志中包含多个事件详情等。在这种情况下，如何对数组内部的数据进行准确统计分析，是聚合分析中的常见需求。 Easysearch 支持嵌套（nested）聚合和反向嵌套（reverse_nested）聚合，帮助开发者针对嵌套对象字段进行精细统计和关联分析。本文从基础讲起，结合实例与可视化思路，带你快速掌握这两种高级聚合方式。 … - [Easysearch 文本分析：Analyzer 的工作原理解析](https://easysearch.cn/knowledge-base/basic/easysearch-text-analysis-analyzer-principle/): 作为一名搜索研发工程师，我深知在构建搜索系统时，最让开发者困惑的往往不是如何存储数据，而是：为什么我搜“北京”，却搜不到“北京市”？这一切的答案，都隐藏在搜索引擎的“中央处理器”——**分析器（Analyzer）**之中。在 Easysearch 中，文本分析不仅是搜索的第一步，更是决定搜索质量的基石。本文将深入浅出地为你解析 Easysearch 文本分析的工作原理。 一、 … - [Elasticsearch 供应链风险分析：从许可证变更到地缘政治影响](https://easysearch.cn/knowledge-base/insight/elasticsearch-supply-chain-risk-analysis-from-license-change-to-geopolitical-impact/): 当一家跨国企业的技术团队在 2021 年初收到法律部门的紧急通知，要求评估其全球日志系统因 Elasticsearch 许可证变更带来的合规风险时，他们意识到技术选型已不再纯粹是性能与成本的权衡。 技术供应链的稳定性，正成为全球企业数字化基础中最为脆弱的一环。 2022 年 3 月，Elastic 公司遵循国际制裁规定，终止了对俄罗斯地区客户的产品销售、服务和支持，这一事件如同一道闪电，照亮了长 … - [Fetch fields 参数不能为空 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/fetch-fields-parameter-must-not-be-empty-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.2-8.9 1. 错误异常的基本描述 # Fetch fields 参数不能为空 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Fetch Shard Store 线程池保活时间配置](https://easysearch.cn/knowledge-base/easysearch_config/thread_pool.fetch_shard_store.keep_alive/): 配置项作用 # thread_pool.fetch_shard_store.keep_alive 配置项用于控制分片存储元数据获取线程池中弹性线程的保活时间。 当线程数超过核心线程数时，空闲的弹性线程在指定时间后会被回收。 配置项属性 # 配置路径: thread_pool.fetch_shard_store.keep_alive 数据类型: TimeValue（时间值） 默认值: 5m（5 … - [hostsSetting.getKey()的主机列表为空 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/host-list-for-hostssetting-getkey-is-empty-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.5-8.9 1. 错误异常的基本描述 # hostsSetting.getKey()的主机列表为空 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返 … - [index [indexName] not found in repository [repoName] - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/Index-indexName-not-found-in-repository-repoName-How-to-solve-this-Elasticsearch-exception/): 适用版本： 7.12-8.9 1. 错误异常的基本描述 # index [indexName] not found in repository [repoName] 表示当前请求需要从快照仓库中解析某个索引，但仓库元数据里不存在该索引记录。它常见于恢复指定索引、分析快照内容、按索引过滤恢复对象时。 常见现象 # 恢复接口指定了某个索引名，但请求立即失败。 同一个快照可以列出来，但其中某些索 … - [MLT查询不支持currentFieldName – 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/mlt-query-does-not-support-currentfieldname-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # MLT查询不支持currentFieldName 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [recovery was canceled reason [reason] - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/recovery-was-canceled-reason-reason-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # recovery was canceled reason [reason] 表示某个分片恢复流程已经被框架主动终止。取消的原因会被拼进异常消息里；如果取消时分片已经关闭，还可能转成 IndexShardClosedException。 常见现象 # 分片恢复进行到一半突然中断。 同一时间窗口可能伴随节点离线、分片关闭、重新分配或新的 … - [TCP 发送缓冲区大小配置](https://easysearch.cn/knowledge-base/easysearch_config/network.tcp.send_buffer_size/): 配置项作用 # network.tcp.send_buffer_size 配置项用于控制TCP 套接字的发送缓冲区大小。 此配置决定了操作系统为 TCP 连接分配的发送缓冲区大小，影响网络数据的发送性能和内存使用。 配置项属性 # 配置路径: network.tcp.send_buffer_size 数据类型: ByteSizeValue（字节大小值） 默认值: -1（不设置，使用系统默认） … - [uuid [repositoryUuid]; original name [originalName] - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/uuid-repositoryuuid-original-name-originalname-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.12-8.9 1. 错误异常的基本描述 # 某些仓库内部流程不会只按仓库名称工作，而是按仓库元数据里的 UUID 定位具体仓库实例。如果遍历当前已注册仓库后，仍找不到对应 UUID，就会抛出 uuid [repositoryUuid]; original name [originalName] 形式的 RepositoryMissingException。 常见现象 # 仓 … - [不可配置 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/is-not-configurable-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 不可配置 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返回 400、404、409、429、500 … - [分片分配磁盘水位配置](https://easysearch.cn/knowledge-base/easysearch_config/cluster.routing.allocation.disk.watermark.flood_stage/): 配置项概述 # 磁盘水位配置项用于控制基于磁盘使用率的分片分配决策。 配置项 默认值 说明 cluster.routing.allocation.disk.watermark.low 85% 低水位 cluster.routing.allocation.disk.watermark.high 90% … - [发现非 master-eligible 节点 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/non-master-eligible-node-found-how-to-solve-this-elasticsearch-exception/): 适用版本： 7-8 1. 错误异常的基本描述 # 发现非 master-eligible 节点 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [在字段中发现脱敏密码 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/found-redacted-password-in-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 在字段中发现脱敏密码 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无效的分组类型 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/invalid-grouping-type-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.2-7.17 1. 错误异常的基本描述 # 无效的分组类型 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无效的索引模板 (invalid_index_template_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/invalid_index_template_exception/): 为什么这个错误发生 # invalid_index_template_exception 表示索引模板配置无效或存在错误。 如何修复 # 1. 验证模板配置 # 检查模板语法和配置是否正确。 2. 检查详细错误 # # 错误响应包含具体原因 { "error": { "type": … - [无法在当前节点版本上持久化 Job 请求 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-persist-job-request-getjobid-on-node-with-version-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # Cannot persist job [job_id] on node with version x.y.z 表示 Elasticsearch 在执行机器学习（ML）Job 的持久化操作时，发现负责执行该请求的节点版本过低，不支持当前 ML 元数据持久化流程，因此在真正执行前就拒绝了请求。 该异常通常出现在混合版本集群或滚动升级尚未完 … - [无法序列化 ID 为 config.getId() 的数据框分析 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-serialise-data-frame-analytics-with-id-config-getid-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.16-8.9 1. 错误异常的基本描述 # 无法序列化 ID 为 config.getId() 的数据框分析 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法汇总索引 originalIndex](https://easysearch.cn/knowledge-base/elasticsearch_error/unable-to-rollup-index-originalindex-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.12-8.2 1. 错误异常的基本描述 # 无法汇总索引 originalIndex 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法解析监视器触发事件，期望触发器主体是对象（Could not parse trigger event for ... expected trigger an object as the trigger body）- 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-trigger-event-for-for-watch-expected-trigger-an-object-as-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.x 1. 错误异常的基本描述 # could not parse trigger event for [...] for watch [...]. expected trigger an object as the trigger body; but found [...] 表示 Watcher 在解析触发事件时，已经识别出了触发器类型字段，但这个字段对应的值不是对象。 … - [本地节点不是主节点——如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/local-node-is-not-master-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # 本地节点不是主节点— 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [查询不支持 currentFieldName – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/query-does-not-support-currentfieldname-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 查询不支持 currentFieldName 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [查询未指定字段名 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/no-fieldname-specified-for-query-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.8-8.9 1. 错误异常的基本描述 # 查询未指定字段名 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [模式集过于复杂无法评估 – 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/the-set-of-patterns-is-too-complex-to-evaluate-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.12-8.6 1. 错误异常的基本描述 # 模式集过于复杂无法评估 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [模板必须设置 match、path_match 或 match_mapping_type - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/template-must-have-match-path-match-or-match-mapping-type-set-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.12 1. 错误异常的基本描述 # 模板必须设置 match、path_match 或 match_mapping_type 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态 … - [此节点之前加入的集群 UUID 不同 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/this-node-previously-joined-a-cluster-with-uuid-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.12-7.15 1. 错误异常的基本描述 # 此节点之前加入的集群 UUID 不同 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [索引验证失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-verify-index-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 索引验证失败 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [获取文档](https://easysearch.cn/knowledge-base/easysearch_api/get-document/): 根据文档 ID 获取文档内容、源字段或检查文档是否存在。 API # GET /{index}/_doc/{id} HEAD /{index}/_doc/{id} GET /{index}/_doc/{id}/_source HEAD /{index}/_doc/{id}/_source GET /{index}/{type}/_doc/{id} API 的作用 # 该 API … - [解析SAML消息失败 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-saml-message-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.7-8.9 1. 错误异常的基本描述 # 解析SAML消息失败 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [跨集群复制跟随者恢复块大小配置](https://easysearch.cn/knowledge-base/easysearch_config/plugins.replication.follower.index.recovery.chunk_size/): 配置项作用 # plugins.replication.follower.index.recovery.chunk_size 配置项用于控制领导者与跟随者索引之间恢复操作期间使用的块大小。 配置项属性 # 配置路径: plugins.replication.follower.index.recovery.chunk_size 数据类型: ByteSizeValue（字节大小） 默认值: … - [连接异常 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/connect-exception-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # connect_exception 通常表示连接在真正发送请求之前就失败了，常见场景包括 Java 客户端连不上 Elasticsearch 节点、集群节点之间的 transport 连接建立失败、跨集群搜索连接远端集群失败，或者连接刚建立就被对端关闭。从当前源码片段看，这类错误最终由 ConnectTransportException … - [通用节点连接失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/general-node-connection-failure-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 通用节点连接失败 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [集群发现配置: probe.connect_timeout](https://easysearch.cn/knowledge-base/easysearch_config/discovery.probe.connect_timeout/): discovery.probe.connect_timeout 配置项控制集群发现相关行为。 配置格式 # # 默认配置 discovery.probe.connect_timeout: default - [非Leader节点拒绝Leader检查——如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/non-leader-rejecting-leader-check-how-to-solve-this-elasticsearch-exception/): 适用版本： 7-7.4 1. 错误异常的基本描述 # 非Leader节点拒绝Leader检查— 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [页面缓存Object[] 类型页面的权重配置](https://easysearch.cn/knowledge-base/easysearch_config/cache.recycler.page.weight.objects/): 配置项作用 # cache.recycler.page.weight.objects 配置项控制 objects 类型页面在页面缓存中的内存分配权重。 默认值 # 配置类型 # 静态配置 取值范围 # 配置格式 # # 默认配置 cache.recycler.page.weight.objects: 0.1 # … - [cannot authenticate unwrapped requests - 无法认证未封装的请求如何解决](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-authenticate-unwrapped-requests-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.9 1. 错误异常的基本描述 # Cannot authenticate unwrapped requests 表示 Elasticsearch 收到一个请求，该请求没有按照认证上下文的要求正确封装。只有通过 wrapAsMessageWithAuthenticationContext 之类的封装方式，认证上下文才能随请求一起传递。如果请求未被正确包装，认证链无法处理该请求，从 … - [CORS 允许的请求头配置](https://easysearch.cn/knowledge-base/easysearch_config/http.cors.allow-headers/): 配置项作用 # http.cors.allow-headers 配置项用于指定在跨域资源共享（CORS）请求中允许浏览器发送的自定义 HTTP 请求头列表。 当浏览器发送跨域请求时，如果请求包含自定义头部，服务器需要在响应的 Access-Control-Allow-Headers 中明确声明允许这些头部，浏览器才会允许请求通过。 配置项属性 # 配置路径: … - [Easysearch vs MySQL](https://easysearch.cn/knowledge-base/basic/easysearch-vs-mysql-search-engine-database-comparison/): 在数据存储与检索的技术选型中， Easysearch 与 MySQL 常被置于对比场景——前者是基于 Lucene 内核的开源搜索引擎，后者是主流关系型数据库。两者看似都能处理“数据查询”需求，但核心定位、技术架构与适用场景存在本质差异。 一、核心定位：各司其职的技术赛道 # 两者的核心差异源于定位不同，决定了它们在技术体系中的核心价值： MySQL：关系型数据库的典型代表，核心定位是“结构化 … - [Easysearch：动态 Mapping 是帮手，还是定时炸弹？](https://easysearch.cn/knowledge-base/usage/easysearch-dynamic-mapping-helper-or-time-bomb/): 一、动态 Mapping：自动建字段的核心优势 # 动态 Mapping 作为 Easysearch 的核心特性，其自动建字段功能在特定场景下展现出显著价值： 1. 快速部署，降低开发门槛 # 无需提前定义完整字段结构，开发者可直接写入异构数据，系统通过智能算法自动推断字段类型（如整数、日期、文本等）。例如日志分析场景中，不同应用的日志字段差异较大，动态 Mapping 可自动适 … - [Expected one of XContentParser Token VALUE BOOLEAN - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/expected-one-of-xcontentparser-token-value-boolean-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # Expected one of XContentParser Token VALUE BOOLEAN 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与 … - [failed to load nori user dictionary - Nori 用户词典加载失败](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-load-nori-user-dictionary-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # failed to load nori user dictionary 与 Kuromoji 场景类似，发生在 Nori 分词器（用于韩语文本分析）初始化用户词典时。源码先逐行拼接规则，再调用 UserDictionary.open(rulesReader)；若词典读取抛出 IOException，就会变成当前异常。 这不是搜索执行失 … - [failed to load settings from [resourceName] - 从资源名加载设置失败](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-load-settings-from-resourcename-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Failed to load settings from [resourceName] 说明 Elasticsearch 已经拿到一个资源名，并尝试通过解析器读取其内容，但在 put(fromXContent(...)) 过程中失败。源码对 ElasticsearchParseException 会直接抛出， … - [fetch_fields 的 field 参数必须提供 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/field-parameter-of-fetch-fields-must-be-provided-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.2-8.9 1. 错误异常的基本描述 # fetch_fields 的 field 参数必须提供 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可 … - [Get uri was cancelled – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/get-uri-was-cancelled-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.2-8.9 1. 错误异常的基本描述 # Get uri was cancelled 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [HipChat 账户缺少必需的认证令牌设置 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/hipchat-account-name-missing-required-auth-token-setting-setting-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # hipchat account [name] missing required [auth_token] setting 是 Elasticsearch Watcher 中 HipChat 通知动作配置不完整时抛出的异常。当 Watcher 尝试发送 HipChat 消息，但对应的 HipChat 账户未在设置中提供认证令 … - [privileges check 解析失败：出现未预期字段 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-privileges-check-unexpected-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # 当权限检查请求中带了未被支持的字段时，会看到： failed to parse privileges check [description]. unexpected field [fieldName] 2. 为什么会发生这个错误 # 这不是权限不足，而是接口入参字段超出了允许范围。 … - [SAML消息无法进行Base64解码 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/saml-message-cannot-be-base64-decoded-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.7-8.9 1. 错误异常的基本描述 # SAML消息无法进行Base64解码 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [SearchApplication BINARY CONTENT FIELD getPreferredName 字段缺失 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/searchapplication-binary-content-field-getpreferredname-field-is-missing-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.8-8.9 1. 错误异常的基本描述 # SearchApplication BINARY CONTENT FIELD getPreferredName 字段缺失 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要 … - [Span first 必须设置 end 参数 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/span-first-must-have-end-set-for-it-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Span first 必须设置 end 参数 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [TCP 保持连接配置](https://easysearch.cn/knowledge-base/easysearch_config/network.tcp.keep_alive/): 配置项作用 # network.tcp.keep_alive 配置项控制是否启用 TCP 的 SO_KEEPALIVE 选项。启用后，操作系统会定期发送保活数据包来检测连接是否仍然有效，防止长时间空闲连接被中间设备（如防火墙、NAT 路由器）断开。 配置项类型 # 该配置项为静态配置，需要在启动时设置，修改后需要重启节点才能生效。 默认值 # true（启用保持连接） 是否必需 # 可选配 … - [Terms 聚合中参数 min_doc_count 和 shardMinDocCount 必须大于等于 0 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/parameter-min-doc-count-and-shardmindoccount-must-be-0-in-terms-aggregation-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Terms 聚合中参数 min_doc_count 和 shardMinDocCount 必须大于等于 0 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、 … - [Zen发现主机提供者配置](https://easysearch.cn/knowledge-base/easysearch_config/discovery.zen.hosts_provider/): 配置项作用 # discovery.zen.hosts_provider 配置项用于指定集群发现过程中使用的种子主机提供者列表。 此配置定义了节点如何获取集群中其他节点的地址信息，以便发现并加入集群。 配置项属性 # 配置路径: discovery.zen.hosts_provider 数据类型: list（字符串列表） 默认值: []（空列表） 是否可选: 是 弃用状态: ⚠️ 已弃用 … - [主节点选举持续时间配置](https://easysearch.cn/knowledge-base/easysearch_config/cluster.election.duration/): 配置项作用 # cluster.election.duration 配置项指定每次主节点选举尝试的持续时间。此配置控制候选主节点在选举过程中等待其他节点响应的最长时间。 配置项类型 # 该配置项为静态配置，需要在启动时设置，修改后需要重启节点才能生效。 默认值 # 500ms（500毫秒） 是否必需 # 可选配置项（有默认值） 取值范围 # 1ms ~ 300s（300秒） 配置格式 # … - [发布 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/publication-how-to-solve-this-elasticsearch-exception/): 适用版本： 7-7.15 1. 错误异常的基本描述 # 发布 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返回 400、404、409、429、500 或 503 … - [启动数据馈送参数 getDatafeedId 在超时后超时 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/starting-datafeed-params-getdatafeedid-timed-out-after-timeout-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.16-8.4 1. 错误异常的基本描述 # 启动数据馈送参数 getDatafeedId 在超时后超时 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可 … - [响应处理失败传输异常 (response_handler_failure_transport_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/response_handler_failure_transport_exception/): 为什么这个错误发生 # response_handler_failure_transport_exception 表示在处理传输操作的响应时失败。这通常发生在客户端接收远程节点返回的响应并尝试处理时。 这个错误可能由以下原因引起： 响应处理失败：响应处理逻辑执行失败 反序列化错误：响应对象反序列化失败 版本不兼容：不同节点的响应格式不兼容 网络中断：在接收响应时网络中断 响应超时： … - [字段数据缓存配置](https://easysearch.cn/knowledge-base/easysearch_config/indices.fielddata.cache.size/): 配置项作用 # indices.fielddata.cache.size 配置项控制用于缓存字段数据（fielddata）的 JVM 堆内存大小。字段数据缓存用于加速对文档字段的排序、聚合和分析操作。 配置项类型 # 该配置项为动态配置，可以在运行时通过索引设置 API 进行修改。 默认值 # -1b（不限制） 是否必需 # 可选配置项（有默认值） 配置格式 # # 索引级别配置 PUT … - [实际参数不足 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/not-enough-actual-parameters-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 实际参数不足 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [强制合并索引](https://easysearch.cn/knowledge-base/easysearch_api/force-merge-index/): 强制合并索引的段文件，减少段数量，提高查询性能并释放存储空间。 API # POST /_forcemerge POST /{index}/_forcemerge API 的作用 # 该 API 用于强制合并索引的段文件（segments），主要作用包括： 减少段数量：将多个小段合并为较少的大段 提高查询性能：减少需要搜索的段数量 释放存储空间：清除已删除的文档 优化索引结构： … - [无法检索数据，因为索引 IndexNotFoundException 导致 getIndex 不存在 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-retrieve-data-because-index-indexnotfoundexception-cause-getindex-does-not-exist-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.5-8.9 1. 错误异常的基本描述 # 无法检索数据，因为索引 IndexNotFoundException 导致 getIndex 不存在 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文 … - [期望字段名但得到解析器当前标记 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/expected-field-name-but-got-parser-currenttoken-how-to-solve-this-elasticsearch-exception/): 适用版本： 7-8.9 1. 错误异常的基本描述 # 期望字段名但得到解析器当前标记 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [期望开始对象 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/start-object-expected-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.17 1. 错误异常的基本描述 # 期望开始对象 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [正则表达式规则文件格式错误：数组后缺少字段名 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/malformed-regular-expression-file-should-continue-with-field-name-after-array-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 解析正则表达式规则文件时，如果数组结构后面没有接字段名，会看到： malformed regular expression file; should continue with 'field_name' after 'array' 2. 为什么会发生这个错误 # 这是规则文件结构错误，不是查询 DSL … - [没有足够的主节点确认已发送的集群状态——如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/not-enough-masters-to-ack-sent-cluster-state-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # 没有足够的主节点确认已发送的集群状态— 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [线程在尝试获取分片锁时被中断 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/thread-interrupted-while-trying-to-obtain-shard-lock-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 线程在尝试获取分片锁时被中断 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [试图获取作业管理器但机器学习功能已禁用——如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/tried-to-get-job-manager-although-machine-learning-is-disabled-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 试图获取作业管理器但机器学习功能已禁用— 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [间隔查询定义中缺少间隔 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/missing-intervals-from-interval-query-definition-how-to-solve-this-elasticsearch-exception/): 适用版本： 7-8.9 1. 错误异常的基本描述 # 间隔查询定义中缺少间隔 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [集群信息更新超时配置](https://easysearch.cn/knowledge-base/easysearch_config/cluster.info.update.timeout/): 配置项作用 # cluster.info.update.timeout 配置项用于控制集群信息收集操作的超时时间。 当 InternalClusterInfoService 从集群中收集节点统计信息（NodeStats）和索引统计信息（IndicesStats）时，此配置限制了等待响应的最长时间。 配置项属性 # 配置路径: cluster.info.update.timeout 数据类型: … - [a filter with id does not exist - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/a-filter-with-id-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # a filter with id [xxx] does not exist 是 Elasticsearch 在管理保存的过滤器（saved filters）时抛出的异常。当你尝试访问、更新或删除一个不存在的过滤器 ID 时，就会触发此错误。Elasticsearch 的过滤器功能（如 Kibana 的 saved filters … - [azure proxy port or host have been set but proxy type is not defined - Azure 代理配置缺少类型如何解决](https://easysearch.cn/knowledge-base/elasticsearch_error/azure-proxy-port-or-host-have-been-set-but-proxy-type-is-not-defined-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Azure Proxy port or host have been set but proxy type is not defined 表示在配置 Elasticsearch 的 Azure 快照仓库（Snapshot Repository）时，代理配置不完整：设置了 proxy.host 或 proxy.port， … - [Easysearch Match 和 Term 正确使用姿势](https://easysearch.cn/knowledge-base/usage/easysearch-match-vs-term-query-guide/): 在 Easysearch 的使用过程中，无论是新手还是有一定经验的开发者，经常会对 match 和 term 这两种最基础的查询方式感到困惑。选择不当往往导致搜索结果与预期大相径庭——要么搜不到任何内容，要么返回一大堆不相关的结果。 理解 match 查询和 term 查询的根本差异，是掌握 Easysearch 搜索精准度的关键第一步。 1. 核心概念速览：当搜索遇见索引 # 在深入对比之前， … - [Easysearch 开发者入门](https://easysearch.cn/knowledge-base/basic/easysearch-developer-getting-started/): 前言 - 什么是 Easysearch # 在介绍 Easysearch 之前，我们无法绕过 Elasticsearch（简称 ES）。作为全文检索领域的绝对霸主，ES 几乎是所有搜索和日志分析场景的首选。但是， 自 2021 年 ES 宣布修改开源协议（从 Apache 2.0 变更为 SSPL）后，以及同年 Elastics 解散了中国的直销团队，许多企业和开发者开始寻求更稳定、协议更友好的 … - [Elasticsearch 无法删除保留租约 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/es-failed-to-remove-retention-leases-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Elasticsearch 无法删除保留租约 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [GROUP BY ALL 不受支持 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/group-by-all-is-not-supported-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # GROUP BY ALL 不受支持 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Join键只能使用一次，发现重复项 – 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/join-keys-must-be-used-only-once-found-duplicates-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.6-8.9 1. 错误异常的基本描述 # Join键只能使用一次，发现重复项 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [NAME 未找到子类型的关系 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/name-no-relation-found-for-child-type-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # NAME 未找到子类型的关系 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Script query 不支持 currentFieldName - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/script-query-does-not-support-currentfieldname-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Script query 不支持 currentFieldName 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [SyncFlush 仅在引擎不在恢复模式时允许 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/syncflush-is-only-allowed-if-the-engine-is-not-recovery-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.4 1. 错误异常的基本描述 # SyncFlush 仅在引擎不在恢复模式时允许 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返 … - [Version string expected min version - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/version-string-expected-min-version-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.6-7.9 1. 错误异常的基本描述 # Version string expected min version 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 … - [Watch HTTP 附件请求返回空响应体 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/watch-attachment-http-empty-response-body-host-port-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # 当 Elasticsearch Watcher 通过 HTTP 请求拉取附件（attachment 输入类型）时，如果远端服务返回的 HTTP 响应状态码符合要求，但响应体（response body）为空，就会触发 ElasticsearchException: Watch[...] attachment[...] HTTP … - [保留租约无效的保留序列号异常 (retention_lease_invalid_retaining_sequence_number_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/retention_lease_invalid_retaining_sequence_number_exception/): 为什么这个错误发生 # retention_lease_invalid_retaining_sequence_number_exception 表示尝试更新保留租约时，新的保留序列号小于现有租约的序列号。保留租约用于确保软删除的文档不会被过早清理。 这个错误可能由以下原因引起： 序列号递减：尝试用更小的序列号更新租约 旧副本请求：来自旧副本的恢复请求 时序混乱：操作的时序混乱导致序列号不正确 … - [动态映射更新超时配置](https://easysearch.cn/knowledge-base/easysearch_config/indices.mapping.dynamic_timeout/): 配置项作用 # indices.mapping.dynamic_timeout 配置项控制动态映射更新操作的超时时间。当文档包含新字段且启用了动态映射时，系统会自动更新索引映射。此配置控制该操作的最大等待时间。 配置项类型 # 该配置项为动态配置，可以在运行时通过索引设置 API 进行修改。 默认值 # 30s 是否必需 # 可选配置项（有默认值） 取值范围 # 0 ~ … - [发布失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/publishing-failed-how-to-solve-this-elasticsearch-exception/): 适用版本： 7-8.8 1. 错误异常的基本描述 # 发布失败 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返回 400、404、409、429、500 … - [发现无效数字 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/invalid-number-found-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 发现无效数字 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [命令缺少from_node参数 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/command-missing-the-from-node-parameter-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 命令缺少from_node参数 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [多点数据提供了但期望单点数据 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/multipoint-data-provided-when-single-point-data-expected-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 多点数据提供了但期望单点数据 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [字段仅支持特定类型 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/field-is-supported-for-only-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 字段仅支持特定类型 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [已为密钥设置用户名但类型不正确 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/username-for-key-is-set-but-type-is-type-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.6-8.9 1. 错误异常的基本描述 # 已为密钥设置用户名但类型不正确 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无已知主节点——如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/no-known-master-node-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.17 1. 错误异常的基本描述 # 无已知主节点— 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无效的token文档 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/invalid-token-document-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.2-8.9 1. 错误异常的基本描述 # 无效的token文档 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无效的比例或百分比 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/invalid-ratio-or-percentage-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 无效的比例或百分比 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [未找到字段映射以进行排序 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/no-mapping-found-for-fieldname-in-order-to-sort-on-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 未找到字段映射以进行排序 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [格式错误 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/malformed-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # 格式错误 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [每节点常规操作连接数配置](https://easysearch.cn/knowledge-base/easysearch_config/transport.connections_per_node.reg/): 配置项作用 # transport.connections_per_node.reg 配置项控制集群中每个节点之间用于常规操作（Regular Operations）的并发连接数。常规操作包括搜索请求、单文档索引、获取文档等日常操作。这是最常用的连接类型，对集群整体性能影响最大。 配置项类型 # 该配置项为静态配置，需要在启动时设置，修改后需要重启节点才能生效。 默认值 # 6 是否必需 # … - [索引不存在且自动创建索引设置被禁用 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/no-such-index-and-auto-create-index-setting-getkey-contains-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-6.8 1. 错误异常的基本描述 # 索引不存在且自动创建索引设置被禁用 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [索引压缩编解码器配置](https://easysearch.cn/knowledge-base/easysearch_config/config_index.codec/): 配置项作用 # index.codec 配置项指定索引使用的 Lucene 压缩编解码器（Codec）。编解码器决定了数据在磁盘上的压缩格式，影响存储空间、索引性能和查询性能。 配置项类型 # 该配置项为静态配置，只在写入新段时生效，不支持实时更新。 默认值 # default（LZ4 压缩） 是否必需 # 可选配置项（有默认值） 可选值 # … - [自适应副本选择配置](https://easysearch.cn/knowledge-base/easysearch_config/cluster.routing.use_adaptive_replica_selection/): 配置项作用 # cluster.routing.use_adaptive_replica_selection 配置项用于控制是否启用**自适应副本选择（Adaptive Replica Selection, ARS）**功能。 自适应副本选择是一种智能查询路由策略，它会根据各副本节点的实时性能统计信息，动态选择最优的副本来处理查询请求。 配置项属性 # 配置路径: … - [节点关闭时发生故障 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failure-occurred-while-shutting-down-node-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.9-8.9 1. 错误异常的基本描述 # 节点关闭时发生故障 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [重新加载安全设置](https://easysearch.cn/knowledge-base/easysearch_api/reload-security-settings/): 从密钥库（keystore）文件重新加载安全设置到集群节点，无需重启节点即可动态更新敏感配置（如密码、加密密钥等）。 API 格式 # POST /_nodes/reload_secure_settings POST /_nodes/{node_id}/reload_secure_settings API 作用 # 该 API 允许管理员动态重新加载存储在密钥库文件中的敏感配置设置，而无需重启 … - [集群发现配置: find_peers_interval](https://easysearch.cn/knowledge-base/easysearch_config/discovery.find_peers_interval/): discovery.find_peers_interval 配置项控制集群发现相关行为。 配置格式 # # 默认配置 discovery.find_peers_interval: default - [页面缓存long[] 类型页面的权重配置](https://easysearch.cn/knowledge-base/easysearch_config/cache.recycler.page.weight.longs/): 配置项作用 # cache.recycler.page.weight.longs 配置项控制 longs 类型页面在页面缓存中的内存分配权重。 默认值 # 配置类型 # 静态配置 取值范围 # 配置格式 # # 默认配置 cache.recycler.page.weight.longs: 1.0 # 增加权重 cache.recycler.page.weight.longs: 2.0 - [cannot parse empty date - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-parse-empty-date-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.0-8.9 1. 错误异常的基本描述 # cannot parse empty date 是 Elasticsearch 在解析日期字段时抛出的异常。当你向一个日期类型的字段（date、date_nanos）写入空字符串 "" 时，Elasticsearch 的日期解析器会在最入口处检查值是否为空，如果为空则直接抛出此异常。这意味着问题不在日期格式本身，而在 … - [CurrentFieldName值必须是正整数——如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/currentfieldname-value-must-be-a-positive-integer-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # CurrentFieldName值必须是正整数— 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返 … - [Easysearch 写入一条数据，背后发生了什么](https://easysearch.cn/knowledge-base/basic/easysearch-what-happens-when-writing-data/): 当我们向 Easysearch 发送一个简单的 PUT /my_index/_doc/1 请求，并收到 200 OK 的响应时，数据似乎瞬间就“写进去了”。然而，在这短短的毫秒之间，你发送的 JSON 数据其实经历了一场精密而复杂的内部旅程，它不仅要确保自身不丢失，还要为未来的快速搜索做好准备。 今天，我们就深入 Easysearch 的“幕后”，一步步揭示一条数据从接收到最终可被搜索的全过程。 … - [Easysearch 快照与备份的正确使用方式](https://easysearch.cn/knowledge-base/usage/easysearch-snapshot-and-backup-best-practices/): 在分布式搜索引擎的运维中，数据安全永远是“1”前面的那个“0”。无论是为了应对突发的硬件故障、人为的误操作，还是勒索软件的攻击，一套完善的备份恢复机制都是企业级数据架构的底线。 INFINI Easysearch 作为一款自主可控、高性能的分布式近实时搜索与分析引擎，不仅完全兼容 Elasticsearch 的快照（Snapshot）API，更在此基础上提供了**可搜索快照（Searchable … - [FieldType名称配置为仅接受点数据但传入其他数据类型——如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/fieldtype-name-is-configured-for-points-only-but-a-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # FieldType名称配置为仅接受点数据但传入其他数据类型— 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [HNSW索引选项需要配置ef_construction字段——如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/index-options-of-type-hnsw-requires-field-ef-construction-to-be-configured-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # HNSW索引选项需要配置ef_construction字段— 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [JDK不支持线程等待阻塞时间统计 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/thread-wait-blocked-time-accounting-is-not-supported-on-this-jdk-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.16-8.9 1. 错误异常的基本描述 # JDK不支持线程等待阻塞时间统计 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [percentage 显著性启发式解析失败：应为空对象 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-percentage-significance-heuristic-expected-an-empty-object-but-got-instead-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # 在使用 Elasticsearch 的 significant_terms 聚合时，如果为 percentage 显著性启发式（significance heuristic）提供了非空的 JSON 对象，Elasticsearch 会在解析 DSL 阶段直接抛出异常，错误信息如下： failed to parse … - [Rollup 最大文档数配置](https://easysearch.cn/knowledge-base/easysearch_config/rollup.max_docs/): 配置项作用 # rollup.max_docs 配置项用于控制Rollup 索引自动滚动前的最大文档数。 当 Rollup 索引达到此文档数时，系统会自动创建新索引，后续的 Rollup 数据将写入新索引。 配置项属性 # 配置路径: rollup.max_docs 数据类型: Long（64位整数） 默认值: 20000000（2000万） 是否可选: 是 作用域: NodeScope（节 … - [Source定义不能包含 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/source-definition-may-not-contain-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Source定义不能包含 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Transport 类型配置](https://easysearch.cn/knowledge-base/easysearch_config/transport.type/): 配置项作用 # transport.type 配置项用于定义传输层实现类型。 配置项属性 # 配置路径: transport.type 数据类型: String（字符串） 默认值: default 是否可选: 是 作用域: NodeScope（节点级别） 动态更新: 否（需要重启节点生效） 配置建议 # 默认配置 # transport: type: default # Netty4 … - [ValuesSource type valuesSource toString is not supported for aggregation - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/valuessource-type-valuessource-tostring-is-not-supported-for-aggregation-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.8-7.8 1. 错误异常的基本描述 # ValuesSource type valuesSource toString is not supported for aggregation 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能 … - [watch condition 出现未知比较运算符 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-condition-for-watch-unknown-comparison-operator-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # could not parse [compare] condition for watch [id]. unknown comparison operator [op] 表示 Watcher compare condition 在解析运算符时，遇到了未注册的操作符名称。 2. 为什么会发生这个错误 # … - [不支持大于3维的地理坐标 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/geo-coordinates-greater-than-3-dimensions-are-not-supported-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 不支持大于3维的地理坐标 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [函数不支持大小写敏感性 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/function-does-not-support-case-in-sensitivity-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.12-8.9 1. 错误异常的基本描述 # 函数不支持大小写敏感性 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [反向嵌套路径不是嵌套类型 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/reverse-nested-nested-path-path-is-not-nested-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8 1. 错误异常的基本描述 # 反向嵌套路径不是嵌套类型 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [安全 SSL 双模式配置](https://easysearch.cn/knowledge-base/easysearch_config/security.ssl.dual_mode.enabled/): 配置项作用 # security.ssl.dual_mode.enabled 配置项用于启用 SSL 双模式功能，允许系统在 SSL-only 模式下同时支持 SSL 和非 SSL 通信协议。 配置项属性 # 配置路径: security.ssl.dual_mode.enabled 数据类型: Boolean（布尔值） 默认值: false 是否可选: 是 作用域: NodeScope（节点 … - [提供的令牌无效 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/supplied-token-is-not-valid-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 提供的令牌无效 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [提供的类型名称与映射定义中的类型名称不匹配 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/type-name-provided-does-not-match-type-name-within-mapping-definition-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.17 1. 错误异常的基本描述 # 提供的类型名称与映射定义中的类型名称不匹配 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法检索数据因为索引 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-retrieve-data-because-index-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.3-7.15 1. 错误异常的基本描述 # 无法检索数据因为索引 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法调度 OPTIONS 请求，因为它们未经过身份验证 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-dispatch-options-request-as-they-are-not-authenticated-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.9-8.9 1. 错误异常的基本描述 # 无法调度 OPTIONS 请求，因为它们未经过身份验证 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返 … - [无法还原部分索引 renamedIndex 因为此类 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-restore-partial-index-renamedindex-because-such-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.5 1. 错误异常的基本描述 # cannot restore partial index [renamedIndex] because such index already exists 表示 Elasticsearch 已经识别到这次请求属于 partial restore，但目标集群里同名索引已经存在，因此恢复在索引级校验阶段被拒绝。 这条异常强调的是“ … - [无活动身份验证 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/no-active-authentication-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.2-8.9 1. 错误异常的基本描述 # 无活动身份验证 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [服务绑定失败 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-bind-service-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 服务绑定失败 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返回 400、404、409、429、500 … - [期望主节点数量配置](https://easysearch.cn/knowledge-base/easysearch_config/gateway.expected_master_nodes/): 配置项作用 # gateway.expected_master_nodes 配置项用于指定集群在恢复状态时期望拥有的主节点数量。 当设置此值后，Gateway 服务会等待直到集群中有指定数量的主节点可用，然后才开始恢复集群状态。 配置项属性 # 配置路径: gateway.expected_master_nodes 数据类型: integer 默认值: -1（表示未设置） 最小值: -1 是 … - [模拟摄入管道执行](https://easysearch.cn/knowledge-base/easysearch_api/simulate-ingest-pipeline/): 在索引前模拟摄入管道对示例文档的处理效果，用于调试和测试管道。 API 格式 # GET /_ingest/pipeline/{id}/_simulate POST /_ingest/pipeline/{id}/_simulate GET /_ingest/pipeline/_simulate POST /_ingest/pipeline/_simulate API 作用 # 该 API 用于 … - [生成映射失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-generate-map-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.1-8.9 1. 错误异常的基本描述 # 生成映射失败 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [短语查询 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/phrase-query-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.3-8.9 1. 错误异常的基本描述 # 短语查询 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返回 400、404、409、429、500 … - [类型不匹配：提供的类型与映射器类型不符 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/type-mismatch-provide-type-source-type-but-mapper-is-of-type-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.11 1. 错误异常的基本描述 # 类型不匹配：提供的类型与映射器类型不符 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [索引分片未设置 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/index-shard-was-not-set-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # 索引分片未设置 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [设置类不存在异常 (no_class_settings_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/no_class_settings_exception/): 为什么这个错误发生 # no_class_settings_exception 表示根据设置值加载类时失败。这通常发生在配置某个插件、分析器、分词器或其他可插拔组件时。 这个错误可能由以下原因引起： 插件未安装：引用的插件类不存在或未安装 类路径错误：类名称配置错误或包名不正确 版本不兼容：类版本与 Easysearch 版本不兼容 类加载失败：类文件损坏或无法加载 依赖缺失：类依赖的其他类或 … - [评分函数score参数格式错误——如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/malformed-score-function-score-parameters-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 评分函数score参数格式错误— 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [跨集群复制跟随者保留租约最大失败持续时间配置](https://easysearch.cn/knowledge-base/easysearch_config/replication.follower.retention_lease_max_failure_duration/): 配置项作用 # replication.follower.retention_lease_max_failure_duration 配置项用于定义跟随者在取消保留租约前可以与领导者失败通信的最长持续时间。 配置项属性 # 配置路径: replication.follower.retention_lease_max_failure_duration 数据类型: TimeValue（时间值） 默 … - [运行时错误 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/runtime-error-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 运行时错误 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [配置驱动的文本提示在 6.0.0 中已弃用，请使用密钥存储库——如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/config-driven-text-prompting-was-deprecated-in-6.0.0-use-the-keystore-how-to-solve-this-elasticsearch-exception/): 适用版本： 7-7.15 1. 错误异常的基本描述 # 配置驱动的文本提示在 6.0.0 中已弃用，请使用密钥存储库— 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口 … - [Easysearch UI 开箱体验](https://easysearch.cn/knowledge-base/basic/easysearch-ui-out-of-box-experience/): 一、开箱前提：5 分钟极速部署 # 作为 Easysearch 1.15.0+ 版本的内置功能，UI 模块无需额外安装插件或第三方软件，真正实现「集群部署即能用」： 部署成本趋近于零：通过 Docker 启动集群后（命令如下），直接访问 https://localhost:9200/_ui/ 即可进入界面 docker run -d --name easysearch --hostname … - [Easysearch 索引别名与索引模板实战](https://easysearch.cn/knowledge-base/usage/easysearch-index-alias-and-template-practices/): 在构建基于 INFINI Easysearch 的企业级搜索与分析平台时，直接操作物理索引往往会带来灵活性差、维护成本高、业务中断风险大等问题。 “别名（Alias）是软链接，模板（Template）是蓝图。” 掌握这两大核心特性，是将 Easysearch 从简单的“数据存储库”升级为“弹性数据服务平台”的关键。本文将深入探讨别名管理、零停机切换策略以及索引模板的自动化配置实战。 一、 索引别 … - [enabled 参数无法为对象映射名称更新 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/the-enabled-parameter-can-t-be-updated-for-the-object-mapping-name-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.8-8.9 1. 错误异常的基本描述 # enabled 参数无法为对象映射名称更新 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [HTTP 管道最大事件数配置](https://easysearch.cn/knowledge-base/easysearch_config/http.pipelining.max_events/): 配置项作用 # http.pipelining.max_events 配置项控制 HTTP 管道中可同时处理的最大请求数量。HTTP 管道允许在不等待响应的情况下发送多个请求，提高性能。 默认值 # 10000 配置类型 # 静态配置 取值范围 # 正整数 配置格式 # # 默认配置 http.pipelining.max_events: 10000 # … - [Mtermvectors 参数不支持 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/mtermvectors-parameter-not-supported-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Mtermvectors 参数不支持 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Rollup 搜索功能开关配置](https://easysearch.cn/knowledge-base/easysearch_config/rollup.search.enabled/): 配置项作用 # rollup.search.enabled 配置项用于控制是否启用 Rollup 搜索功能。 当启用时，系统会启动 RollupListener 组件，该组件负责处理包含 Rollup 索引的搜索请求，自动将查询重写为同时查询原始索引和 Rollup 索引。 配置项属性 # 配置路径: rollup.search.enabled 数据类型: Boolean（布尔值） 默认值: … - [Token malformed - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/token-malformed-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.6 1. 错误异常的基本描述 # Token malformed 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Token元数据未包含有效的IdToken – 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/token-metadata-did-not-contain-a-valid-idtoken-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.2-8.9 1. 错误异常的基本描述 # Token元数据未包含有效的IdToken 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Transport 客户端配置](https://easysearch.cn/knowledge-base/easysearch_config/client.transport/): 注意：Transport Client 已被弃用，推荐使用 High Level REST Client。这些配置主要用于旧版客户端或特定场景。 配置项概述 # client.transport.* 配置项组用于控制 Transport 客户端的行为，包括节点发现、连接验证、集群名称检查等功能。 … - [Unknown node [nodeId] - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unknown-node-nodeid-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # unknown node [nodeId] 表示 Elasticsearch 在执行副本分片操作（如写入复制）时，无法找到分配了该分片的节点。 从源码可见，这个异常在 TransportReplicationAction 中抛出，当 clusterService.state().nodes().get(nodeId) 返回 null 时 … - [Value source of type this value is not supported by scripts - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/value-source-of-type-this-value-is-not-supported-by-scripts-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.6-8.9 1. 错误异常的基本描述 # Value source of type this value is not supported by scripts 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结 … - [weekly day 值既不是字符串也不是数字 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/invalid-weekly-day-value-expected-a-string-or-a-number-value-but-found-token-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # invalid weekly day value. expected a string or a number value; but found [token] 是 Elasticsearch Watcher 模块在解析 weekly 类型定时触发器（schedule）时抛出的解析异常。该错误表示在 day 字段中传入的值既不是合法的字 … - [从 master.dat 读取的种子值与预期不符 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/seed-read-from-master-dat-was-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.4-7.13 1. 错误异常的基本描述 # 从 master.dat 读取的种子值与预期不符 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可 … - [作业调度器线程池队列大小配置](https://easysearch.cn/knowledge-base/easysearch_config/jobscheduler.threadpool.queue_size/): 配置项作用 # jobscheduler.threadpool.queue_size 配置项用于控制作业调度器线程池中待处理任务队列的最大容量。 此配置限制了线程池队列中可以排队的任务数量。当队列满时，新提交的任务将被拒绝。队列大小影响任务的排队能力和内存占用。 配置项属性 # 配置路径: jobscheduler.threadpool.queue_size 数据类型: Integer（整 … - [允许的索引模式集合过于复杂无法评估 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/the-set-of-permitted-index-patterns-is-too-complex-to-evaluate-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.11 1. 错误异常的基本描述 # 允许的索引模式集合过于复杂无法评估 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [删除过期预测失败 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-remove-expired-forecasts-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 删除过期预测失败 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [在watch中期望JSON对象开头 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/expected-starting-json-object-after-in-watch-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 在watch中期望JSON对象开头 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [客户端传输节点检测超时配置](https://easysearch.cn/knowledge-base/easysearch_config/client.transport.ping_timeout/): 配置项作用 # client.transport.ping_timeout 配置项用于设置 TransportClient 在执行节点检测（ping）请求时的超时时间。 当 TransportClient 需要检查节点是否存活或获取集群状态时，会向目标节点发送请求，此配置决定了客户端等待响应的最长时间。如果在此时间内未收到响应，该节点将被视为不可用。 配置项属性 # 配置路径: … - [无效的聚合路径 (invalid_aggregation_path_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/invalid_aggregation_path_exception/): 为什么这个错误发生 # invalid_aggregation_path_exception 表示聚合路径引用不存在的字段或聚合。 如何修复 # 1. 检查聚合路径 # 确保引用的聚合或字段存在。 2. 使用正确的路径 # GET /<index>/_search { "aggs": { "level1": { "terms": … - [无法删除汇总索引 rollupIndex - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unable-to-delete-rollup-index-rollupindex-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.4-8.9 1. 错误异常的基本描述 # 无法删除汇总索引 rollupIndex 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法找到字段字段映射器，未定义缺失值——如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unable-to-find-a-field-mapper-for-field-field-no-missing-value-defined-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 无法找到字段字段映射器，未定义缺失值— 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法汇总索引请求 getSourceIndex - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-rollup-index-request-getsourceindex-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.11-7.11 1. 错误异常的基本描述 # 无法汇总索引请求 getSourceIndex 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法解析 Slack 消息：字段解析失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-slack-message-failed-to-parse-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # 这个异常表示 Watcher 在解析 Slack message 的某个字段时，内部又遇到了一个更底层的解析错误。根据附带源码，典型场景是 from 字段通过 TextTemplate.parse(parser) 解析失败，于是被包装成： could not parse slack message. failed to parse … - [无法解析为 auto:int;int 格式 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-as-a-auto-int-int-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # 无法解析为 auto:int;int 格式 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [更新数据馈送失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-update-datafeed-how-to-solve-this-elasticsearch-exception/): 适用版本： 8-8.9 1. 错误异常的基本描述 # 更新数据馈送失败 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [最大打开滚动上下文配置](https://easysearch.cn/knowledge-base/easysearch_config/search.max_open_scroll_context/): 配置项作用 # search.max_open_scroll_context 配置项限制节点上允许同时打开的最大滚动上下文（Scroll Context）数量。滚动上下文用于维持滚动查询的状态，每个滚动查询都会占用内存和文件句柄等资源。 配置项类型 # 该配置项为动态配置，可以在运行时通过集群设置 API 进行修改。 默认值 # 500 是否必需 # 可选配置项（有默认值） 取值范围 # … - [期望数值类型 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/numeric-value-expected-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 期望数值类型 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [查看索引别名](https://easysearch.cn/knowledge-base/easysearch_api/get-index-alias/): 以表格形式展示索引别名信息，适合人工查看和快速检查。 API # GET /_cat/aliases GET /_cat/aliases/{alias} API 的作用 # 该 API 以表格形式返回索引别名信息，提供人类可读的视图。 vs GET /_aliases # API 返回格式 适用场景 GET /_aliases JSON 程序化处理、API 集成 GET … - [清除应用权限和角色缓存失败——如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/clearing-the-application-privileges-and-role-cache-failed-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.9-7.15 1. 错误异常的基本描述 # 清除应用权限和角色缓存失败— 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [索引的策略策略 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/policy-policy-for-index-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.11 1. 错误异常的基本描述 # 索引的策略策略 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [解析排名请求错误 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/error-parsing-rank-request-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 解析排名请求错误 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [错误描述 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/error-description-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 错误描述 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返回 400、404、409、429、500 … - [a dynamic template must be defined with a name - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/a-dynamic-template-must-be-defined-with-a-name-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # a dynamic template must be defined with a name 是 Elasticsearch 在解析索引映射（mapping）或索引模板（index template）时抛出的异常。当动态模板（dynamic_templates）的定义格式不正确，缺少模板名称时，就会触发此错误。动态模板用于为新增加的字段 … - [API密钥授权认证失败 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-authenticate-api-key-grant-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.7-8.9 1. 错误异常的基本描述 # API密钥授权认证失败 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [API密钥未找到角色描述符 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/no-role-descriptors-found-for-api-key-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # API密钥未找到角色描述符 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Easysearch Bool 查询：写不好就一定慢](https://easysearch.cn/knowledge-base/usage/easysearch-bool-query-performance-guide/): 在 Easysearch 的查询 DSL 中，bool 查询（Boolean Query）无疑是使用频率最高、功能最强大的复合查询类型。它允许我们将多个子查询组合成复杂的逻辑表达式，就像编程语言中的 if (A && B || C) 一样。 然而，越是灵活强大的工具，越容易被误用。在实际生产环境中，大量的慢查询事故都源于对 bool 查询底层机制的误解。很多开发者习惯将所有条件一股 … - [Elasticsearch 国产化迷思：OpenSearch 真是“换汤不换药”吗？](https://easysearch.cn/knowledge-base/insight/elasticsearch-domestic-migration-myth-is-opensearch-just-old-wine-in-a-new-bottle/): 一组泄露自不安全的 Elasticsearch 数据库的数据，包含了超过 2300 万用户的敏感信息，在暗网中被黑客随意叫卖。与此同时，中国某大型互联网公司的技术团队，正将核心搜索服务从国外开源软件迁移到国产自研的搜索基础设施上。 2025 年，信创（信息技术应用创新）战略深入实施，国内企业对技术自主可控的需求达到了前所未有的高度。过去广泛使用的 Elasticsearch 搜索系统，因一系列安 … - [failed to load role query - 角色查询加载失败](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-load-role-query-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.6-8.9 1. 错误异常的基本描述 # Failed to load role query 出现在安全授权链路里。源码在 bitsetCache.getBitSet(roleQuery, in.getContext()) 和 getNumDocs 过程中捕获异常，再包装成当前错误。这说明问题通常发生在 DLS（Document Level Security，文档级安全）角色查 … - [Lucene 的背景——为什么需要搜索引擎](https://easysearch.cn/knowledge-base/basic/lucene-background-why-search-engines-needed/): 对于在单个文件中查找某个单词或短语，这并不是一件复杂的事情。例如，grep 这样的文本搜索工具，在处理少量、结构简单的文本文件时已经足够高效。 但问题在于： 当数据规模上升到“海量”级别时，情况就完全不同了。 在现实世界中，各行各业每天都会产生难以想象的数据量，例如： 百度 每秒要处理数万次搜索请求 抖音 每分钟会有上百万个视频被上传 程序化广告系统每天产生数百亿条广告日志记录 仅仅“收集和存 … - [Property null value cannot be null - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/property-null-value-cannot-be-null-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.1 1. 错误异常的基本描述 # Property null value cannot be null 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 … - [REST 多操作显式索引配置](https://easysearch.cn/knowledge-base/easysearch_config/rest.action.multi.allow_explicit_index/): 配置项概述 # rest.action.multi.allow_explicit_index 配置控制是否在批量操作（Bulk）、多搜索（Multi-Search）和多获取（Multi-Get）请求的请求体中显式指定索引名称。 配置项 默认值 说明 rest.action.multi.allow_explicit_index true … - [TCP 地址重用配置](https://easysearch.cn/knowledge-base/easysearch_config/network.tcp.reuse_address/): 配置项作用 # network.tcp.reuse_address 配置项用于控制是否启用 TCP 套接字的 SO_REUSEADDR 选项。 启用后允许端口在 TIME_WAIT 状态下被重用，避免"地址已在使用"错误，便于服务器快速重启。 配置项属性 # 配置路径: network.tcp.reuse_address 数据类型: Boolean（布尔值） 默认值: 平 … - [不支持的 zero_terms_docs 值 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unsupported-zero-terms-docs-value-zerotermsdocs-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-6.8 1. 错误异常的基本描述 # 不支持的 zero_terms_docs 值 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [不能为空 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-be-empty-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 这里的 cannot be empty 不是通用参数校验，而是快照创建流程在校验 snapshotName 时抛出的 InvalidSnapshotNameException。源码逻辑非常直接：在 validate(repositoryName, snapshotName) 中， … - [发布集群状态失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-publish-cluster-state-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.17 1. 错误异常的基本描述 # 发布集群状态失败 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [发送请求失败 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-sending-request-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.14 1. 错误异常的基本描述 # 发送请求失败 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [在使用新的聚合器之前未调用 PreCollection —— 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/precollection-not-called-on-new-aggregator-before-use-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.5-7.1 1. 错误异常的基本描述 # 在使用新的聚合器之前未调用 PreCollection — 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接 … - [处理器数量配置](https://easysearch.cn/knowledge-base/easysearch_config/processors/): 配置项概述 # processors 配置项设置节点可用的处理器（CPU 核心）线程数，影响系统的并发处理能力。 配置项 默认值 说明 processors 自动检测 处理器数量 配置说明 # processors # 配置项作用：设置节点可用的处理器线程数。此配置影响线程池大小、并发处理能力等。 默认值：自动检测（通常等于 CPU 核心数） 配置类型：静态配置 取值范 … - [多字段中不允许使用include_in_all - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/include-in-all-in-multi-fields-is-not-allowed-found-the-include-in-all-in-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-6.8 1. 错误异常的基本描述 # 多字段中不允许使用include_in_all 表示 mapping 里在不被允许的位置继续声明了 include_in_all。从保留的源码可以看出，这里有两个明确限制：一是 multi-fields 中不能使用它，二是从 6.0 起新建索引整体上也不再支持它，因为 _all 已被废弃。 常见现象 # 创建索引、 … - [字段不支持独立形状 LinearRing - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/field-name-found-and-unsupported-shape-linearring-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.7-8.x 1. 错误异常的基本描述 # Field [name] found and unsupported shape LinearRing 是 Elasticsearch 在处理 geo_shape 类型字段查询时抛出的异常。该错误表明：目标字段确实存在，但传入的几何对象类型是 LinearRing，而 Elasticsearch 并不支持将 LinearRing 作为独 … - [对象映射为数组 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/object-mapping-for-mapper-name-with-array-for-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # 对象映射为数组 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [导入规则库（自动ID覆盖）](https://easysearch.cn/knowledge-base/easysearch_api/import-ruleset-auto-id-overwrite/): 自动生成规则库 ID 并导入规则，使用覆盖模式。如果同 ID 的规则库已存在，将完全替换原有规则。 API 格式 # POST /_match_rules/_import API 作用 # 该 API 用于自动生成规则库 ID 并导入规则： 自动生成 ID：系统自动生成格式为 repo_<timestamp> 的规则库 ID 覆盖模式：如果规则库已存在，完全替换原有规则；否则创建 … - [异步搜索活跃上下文清理间隔](https://easysearch.cn/knowledge-base/easysearch_config/async_search.active.context.reaper_interval/): 配置项作用 # async_search.active.context.reaper_interval 配置项控制异步搜索活跃上下文清理器（Active Context Reaper）的运行间隔。该清理器负责检查并清理已过期或超时运行的异步搜索上下文，释放相关资源。 配置项类型 # 该配置项为静态配置，修改后需要重启节点才能生效。 默认值 # 5m（5分钟） 是否必需 # 可选配置项 取值 … - [无效的间隙策略文本接受的值 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/invalid-gap-policy-text-accepted-values-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # 无效的间隙策略文本接受的值 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法从网关恢复 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-recover-from-gateway-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 无法从网关恢复 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法删除临时汇总索引 tmpIndex - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unable-to-delete-temp-rollup-index-tmpindex-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.12-8.2 1. 错误异常的基本描述 # 无法删除临时汇总索引 tmpIndex 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法解析 Watch 状态：字段必须是字符串 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-watch-status-expecting-field-to-hold-a-string-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.x 1. 错误异常的基本描述 # could not parse watch status. expecting field [<field>] to hold a string value; found [<token>] instead 表示 Watch 状态中的某个字段本应是字符串，但实际读到了别的 token 类型。 从日志上下文可以直接 … - [未找到源 索引/类型/ID – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/source-not-found-index-type-id-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.17 1. 错误异常的基本描述 # 未找到源 索引/类型/ID 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [未知的原因](https://easysearch.cn/knowledge-base/elasticsearch_error/unknown-cause-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 未知的原因 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [注册表不匹配 – 预期值 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/registry-miss-match-expected-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.8-7.9 1. 错误异常的基本描述 # 注册表不匹配 – 预期值 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [聚合中缺少 map_script 字段 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/map-script-field-is-required-in-aggregationname-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.5 1. 错误异常的基本描述 # 聚合中缺少 map_script 字段 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [节点名称配置](https://easysearch.cn/knowledge-base/easysearch_config/node.name/): 配置项作用 # node.name 配置项定义 Easysearch 节点的名称，用于在集群中唯一标识每个节点。节点名称出现在日志、监控和管理界面中，便于识别和管理节点。 配置项类型 # 该配置项为静态配置，需要在启动时设置，修改后需要重启节点才能生效。 默认值 # 机器名的主机名前 8 个字符 + 随机字符 例如：node-1、es-prod-abc123 等 是否必需 # 可选配置项（ … - [路由异常 (routing_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/routing_exception/): 为什么这个错误发生 # routing_exception 是与分片路由相关的通用异常，表示分片分配或路由操作失败。 这个错误可能由以下原因引起： 分片未分配：目标分片未分配到任何节点 路由计算错误：文档路由值计算错误 分配规则限制：分配规则阻止分片分配 节点离线：目标节点离线 索引状态异常：索引处于关闭或不可用状态 如何修复这个错误 # 1. 检查分片状态 # # … - [遇到更高的术语 currentState.term() > used – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/higher-term-encountered-current-currentstate-term-used-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.1-7.15 1. 错误异常的基本描述 # 遇到更高的术语 currentState.term() > used 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常 … - [集群故障检测跟随者检查重试次数配置](https://easysearch.cn/knowledge-base/easysearch_config/cluster.fault_detection.follower_check.retry_count/): 配置项作用 # cluster.fault_detection.follower_check.retry_count 配置项定义了在将一个跟随者（follower）节点标记为故障之前，允许连续检查失败的最大次数。 这是 Easysearch 集群协调机制中的容错配置，用于防止因短暂的网络抖动、GC 停顿或其他临时性问题导致节点被错误地从集群中移除。 配置项属性 # 配置路径: … - [analytics collection does not exists - Analytics Collection 不存在如何解决](https://easysearch.cn/knowledge-base/elasticsearch_error/analytics-collection-does-not-exists-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.8-8.9 1. 错误异常的基本描述 # analytics collection does not exists（注意：原文中 exists 拼写为 exists 的误拼 exists，实际应为 exist）表示在 Elasticsearch 中删除 Analytics Collection（分析集合）时，目标资源不存在，导致删除操作失败。这是一个典型的资源未找到异常， … - [collapse 字段类型不受支持 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unknown-type-for-collapse-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.4 1. 错误异常的基本描述 # 当请求中的 collapse.field 指向了不被支持的字段类型时，Elasticsearch 会报错： unknown type for collapse field `field`; only keywords and numbers are accepted 这类错误通常在构建查询上下文时就会出现，请求会直接失败。 2. 为什么 … - [Easysearch vs ClickHouse 倒排索引技术](https://easysearch.cn/knowledge-base/basic/easysearch-vs-clickhouse-inverted-index-comparison/): 倒排索引是高效文本检索的核心技术， Easysearch 与 ClickHouse 虽均支持该功能，但设计理念、技术架构与适用场景存在本质差异。前者是基于 Lucene 内核、聚焦全文检索的分布式搜索引擎，后者是列式存储的 OLAP 数据库，倒排索引仅为其列式架构的补充模块。本文聚焦两者倒排索引的核心差异，从技术架构、索引构建、核心能力、性能表现及适用场景展开精简对比，为选型提供关键参考。 一、核 … - [HTTP 追踪排除配置](https://easysearch.cn/knowledge-base/easysearch_config/http.tracer.exclude/): 配置项作用 # http.tracer.exclude 配置项指定要从 HTTP 追踪日志中排除的请求模式列表。 默认值 # []（空列表） 配置类型 # 动态配置 配置格式 # # 默认配置：不排除任何请求 http.tracer.exclude: [] # 排除健康检查请求 http.tracer.exclude: - "*/_cluster/health*" - … - [ISM 允许操作列表配置](https://easysearch.cn/knowledge-base/easysearch_config/index_state_management.allow_list/): 配置项作用 # index_state_management.allow_list 配置项控制 ISM 策略中允许执行的操作类型，用于限制可用的 ISM 操作。 是否可选 # 是 默认值 # [alias, allocation, close, delete, force_merge, index_priority, open, read_only, read_write, … - [JVM GC 开销信息阈值配置](https://easysearch.cn/knowledge-base/easysearch_config/monitor.jvm.gc.overhead.info/): 配置项作用 # monitor.jvm.gc.overhead.info 配置项用于控制JVM 垃圾回收（GC）开销的 INFO 级别日志阈值。 当 GC 开销（GC 时间占总时间的百分比）达到或超过此阈值时，系统会记录 INFO 级别的日志，提醒运维人员 GC 压力较大。 配置项属性 # 配置路径: monitor.jvm.gc.overhead.info 数据类型: Integer（整 … - [scroll 上下文中不能关闭 track_total_hits - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/disabling-track-total-hits-is-not-allowed-in-a-scroll-context-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 当请求处于 scroll 上下文，同时又试图关闭或弱化 track_total_hits 时，Elasticsearch 会报： disabling [track_total_hits] is not allowed in a scroll context 2. 为什么会发生这个错误 # scroll 依赖一个稳定的结果遍历上下文。源 … - [slice 数量超过上限 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/the-number-of-slices-numslices-is-too-large-it-must-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-6.8 1. 错误异常的基本描述 # 如果 scroll 查询设置的切片数量过大，会看到报错： The number of slices [numSlices] is too large. It must be less than [sliceLimit]. 2. 为什么会发生这个错误 # slice 用于把 scroll 任务拆成多个并行子任务，但切片数越大，协调开销和 … - [Terms 聚合无法应用于字段 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/terms-aggregation-cannot-be-applied-to-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.7 1. 错误异常的基本描述 # Terms 聚合无法应用于字段 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [不能同时设置mode和enabled参数 – 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-set-both-mode-and-enabled-parameters-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.4-8.9 1. 错误异常的基本描述 # 不能同时设置mode和enabled参数 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [主节点选举忽略非主节点Ping配置](https://easysearch.cn/knowledge-base/easysearch_config/discovery.zen.master_election.ignore_non_master_pings/): 配置项作用 # discovery.zen.master_election.ignore_non_master_pings 配置项用于控制主节点选举过程中是否忽略非主节点的 ping 响应。 当设置为 true 时，只有配置为 node.master: true 的节点才会参与主节点选举；设置为 false 时，所有节点的 ping 响应都会被考虑。 配置项属性 # 配置路径: … - [代理端口必须在 1 到 65534 之间 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/proxy-port-must-be-between-1-and-65534-but-was-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Proxy port must be between 1 and 65534 but was <port> 是 Elasticsearch 在解析代理（Proxy）配置时抛出的 ElasticsearchParseException。当 Elasticsearch 从配置文件、REST API 请求体或仓 … - [任务不支持此操作——如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/task-doesn-t-support-this-operation-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 任务不支持此操作— 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [分片规划，是 Easysearch 稳定运行的第一步](https://easysearch.cn/knowledge-base/usage/easysearch-shard-planning-first-step-for-stability/): 分片（Shard）是 Easysearch 分布式架构的核心单元。分片策略设置得当，集群稳如磐石，性能起飞；设置不当，则可能导致元数据爆炸、Master 节点假死、甚至全集群 OOM。本文将深入解析分片背后的机制，结合 Easysearch 的 ZSTD 压缩特性，提供一套可落地的分片规划黄金法则。 很多用户在从单机测试环境迁移到生产环境时，最容易忽视的就是索引分片（Sharding）的规划。 … - [创建或更新存储脚本](https://easysearch.cn/knowledge-base/easysearch_api/create-or-update-stored-script/): 在集群中创建或更新存储脚本。 API 格式 # POST /_scripts/{id} PUT /_scripts/{id} POST /_scripts/{id}/{context} PUT /_scripts/{id}/{context} API 作用 # 该 API 用于在集群中创建或更新存储脚本： 创建新的可重用脚本 更新已存在的脚本 支持多种脚本语言（ … - [只能在关键字和文本字段上使用前缀查询，不能在[字段类型]上使用——如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/can-only-use-prefix-queries-on-keyword-and-text-fields-not-on-how-to-solve-this-elasticsearch-exception/): 适用版本： 5.x-8.14 1. 错误异常的基本描述 # Can only use prefix queries on keyword and text fields - not on [<type>] which is of type [<type>] 是 Elasticsearch 在执行 前缀查询（prefix query） 时抛出的字段类型不兼容异常。该错误属 … - [字段 currentFieldName 是元数据字段，无法在内部添加 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/field-currentfieldname-is-a-metadata-field-and-cannot-be-added-inside-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.9 1. 错误异常的基本描述 # 字段 currentFieldName 是元数据字段，无法在内部添加 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 … - [导出器正在忙于安装资源 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/exporter-is-busy-installing-resources-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.11-8.9 1. 错误异常的基本描述 # 导出器正在忙于安装资源 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [必须是一个有效数字但实际不是 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/must-be-a-valid-number-but-was-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # 必须是一个有效数字但实际不是 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无效的包SHA - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/invalid-package-sha-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.8-8.9 1. 错误异常的基本描述 # 无效的包SHA 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返回 400、404、409、429、500 … - [无效的时间小时值，期望字符串/数字值或数组 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/invalid-time-hour-value-expected-string-number-value-or-an-array-of-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # 无效的时间小时值，期望字符串/数字值或数组 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法删除ID为filterId的过滤器，因为该过滤器不存在 – 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-delete-filter-with-id-filterid-because-it-does-not-exist-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.16-8.9 1. 错误异常的基本描述 # 无法删除ID为filterId的过滤器，因为该过滤器不存在 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可 … - [无法发现主节点 (master_not_discovered_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/master_not_discovered_exception/): 为什么这个错误发生 # master_not_discovered_exception 表示节点无法发现或连接到集群的主节点。主节点是集群的协调中心，负责管理集群状态、索引创建、分片分配等关键操作。 这个错误可能由以下原因引起： 主节点宕机：主节点进程崩溃或服务器故障 网络问题：节点之间的网络连接中断或配置错误 集群配置问题：discovery.zen.ping.unicast.hosts … - [无法解释 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-explain-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 无法解释 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返回 400、404、409、429、500 … - [未注册的聚合 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unregistered-aggregation-aggregationname-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.8-7.9 1. 错误异常的基本描述 # 未注册的聚合 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [未知的算术运算](https://easysearch.cn/knowledge-base/elasticsearch_error/unknown-arithmetic-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 未知的算术运算 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [等待初始发现状态时中断 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/interrupted-while-waiting-for-initial-discovery-state-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 等待初始发现状态时中断 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [缺少必需的设置configKey - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/missing-required-setting-configkey-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.4 1. 错误异常的基本描述 # 缺少必需的设置configKey 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [脚本查询无法执行时——如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/script-queries-cannot-be-executed-when-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.7-7.15 1. 错误异常的基本描述 # 脚本查询无法执行时— 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [解析 categorizerStats 失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-categorizerstats-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.9-8.9 1. 错误异常的基本描述 # 解析 categorizerStats 失败 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [请求断路器内存限制配置](https://easysearch.cn/knowledge-base/easysearch_config/indices.breaker.request.limit/): 配置项作用 # indices.breaker.request.limit 配置项控制单个请求（如聚合、批量请求）可使用的最大内存。 默认值 # 60%（JVM 堆内存的 60%） 配置类型 # 动态配置 配置格式 # # 默认配置 indices.breaker.request.limit: 60% # 增加限制 indices.breaker.request.limit: 80% - [集群服务在等待移除节点时关闭 – 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cluster-service-closed-while-waiting-for-removal-of-nodes-how-to-solve-this-elasticsearch-exception/): 适用版本： 7-7.15 1. 错误异常的基本描述 # 集群服务在等待移除节点时关闭 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [集群状态发布队列最大长度配置](https://easysearch.cn/knowledge-base/easysearch_config/discovery.zen.publish.max_pending_cluster_states/): 配置项作用 # discovery.zen.publish.max_pending_cluster_states 配置项用于控制待处理集群状态队列（PendingClusterStatesQueue）的最大长度。 当主节点发布集群状态时，如果队列已满，最旧的集群状态会被丢弃，防止队列无限增长导致内存问题。 配置项属性 # 配置路径: … - [could not parse transform for watch missing required field - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-transform-for-watch-missing-required-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # could not parse [TYPE] transform for watch [watchId]. missing required [field] field 是 Elasticsearch Watcher 在解析某个 transform 时抛出的异常。此错误表示 transform 对象缺少必需字段。 从源码看，最直接的场景 … - [data attachment 必须是布尔值或对象 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-data-attachment-expected-either-a-boolean-value-or-an-object-but-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误说明 # could not parse data attachment. expected either a boolean value or an object but found [token] instead 是 Elasticsearch 在解析 data attachment 配置时抛出的类型不匹配异常。该字段只接受两种合法值：布尔 … - [Easysearch 聚合慢，是数据问题还是写法问题？](https://easysearch.cn/knowledge-base/usage/easysearch-aggregation-performance-issues/): 在使用 Easysearch 的过程中，很多人都会遇到一个阶段性问题： 同样是 Aggregations，有的查询毫秒级返回，有的却要好几秒，甚至直接超时。 于是常见的疑问就来了： 是不是数据量太大了？ 是不是集群性能不够？ 还是我写聚合的方式不对？ 本文将从 原理 + 实际问题 两个角度出发，带你一步步拆解：Easysearch 聚合为什么会慢，以及该如何判断和优化。 … - [Lucene 的倒排索引设计（一）](https://easysearch.cn/knowledge-base/basic/lucene-inverted-index-design-part-1/): 倒排索引 # 倒排索引（Inverted Index）是一种数据库索引，存储着从文档中的分词（Term）到文档（Document）的映射。它的主要用途是允许进行快速的全文搜索。 倒排索引的基本结构如下所示： term1 -> <doc_1, doc_2, ..., doc_n> term2 -> <doc_x, doc_y, ...> ... Lucene 在 … - [Refresh 线程池保活时间配置](https://easysearch.cn/knowledge-base/easysearch_config/thread_pool.refresh.keep_alive/): 配置项作用 # thread_pool.refresh.keep_alive 配置项用于控制索引刷新线程池中弹性线程的保活时间。 配置项属性 # 配置路径: thread_pool.refresh.keep_alive 数据类型: TimeValue（时间值） 默认值: 5m（5 分钟） 是否可选: 是 作用域: NodeScope（节点级别） 动态更新: 是（可以动态更新，无需重启） 配 … - [storage_class 不是有效的 S3 存储类型 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/storageclass-is-not-a-valid-s3-storage-class-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # <storage_class> is not a valid S3 Storage Class 表示 Elasticsearch 在解析 S3 仓库配置时，发现 storage_class 不是 AWS SDK 可识别的有效存储类型，因此拒绝创建或使用该仓库配置。 常见现象 # 注册或更新 S3 仓库时直接返回错误。 节 … - [Value source of type - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/value-source-of-type-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.5 1. 错误异常的基本描述 # Value source of type 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [written_by 元数据缺失或无效 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/missing-or-invalid-written-by-writtenby-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # 在恢复、快照或文件元数据解析过程中，如果 written_by 字段为空或非法，Elasticsearch 会报： missing or invalid written_by [value] 2. 为什么会发生这个错误 # 这个异常来自文件元数据解析，不是普通文档字段错误。源码在构造 StoreFileMetadata 前， … - [与远程集群 clusterAlias 通信时出错 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/error-while-communicating-with-remote-cluster-clusteralias-how-to-solve-this-elasticsearch-exception/): 适用版本： 7-8.9 1. 错误异常的基本描述 # 与远程集群 clusterAlias 通信时出错 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [仓库验证异常 (repository_verification_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/repository_verification_exception/): 为什么这个错误发生 # repository_verification_exception 表示在验证快照仓库时发生错误。仓库验证是检查仓库配置、连接性和完整性的过程。 这个错误可能由以下原因引起： 仓库配置错误：仓库配置参数不正确 存储不可访问：无法访问存储系统 认证失败：存储系统认证凭据无效 网络问题：无法连接到存储系统 权限不足：没有权限访问或验证仓库 存储损坏：仓库元数据损坏 并发操 … - [延迟重新路由原因已取消 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/delayed-reroute-reason-cancelled-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.3-8.2 1. 错误异常的基本描述 # 延迟重新路由原因已取消 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [找不到指定ID的模型部署 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/deployment-for-model-with-id-not-found-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.6-8.7 1. 错误异常的基本描述 # 找不到指定ID的模型部署 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [文件系统仓库压缩配置](https://easysearch.cn/knowledge-base/easysearch_config/repositories.fs.compress/): 配置项作用 # repositories.fs.compress 配置项用于控制是否压缩文件系统仓库中的元数据文件。 当启用压缩时，快照的元数据文件（包括集群元数据、索引元数据、快照元数据等）会被压缩存储，从而减少存储空间占用。但实际的数据文件不会被压缩。 配置项属性 # 配置路径: repositories.fs.compress 数据类型: Boolean（布尔值） 默认值: false … - [无效的包大小 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/invalid-package-size-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.8-8.9 1. 错误异常的基本描述 # 无效的包大小 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返回 400、404、409、429、500 … - [无法为活动salt计算密钥 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-compute-secret-key-for-active-salt-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 无法为活动salt计算密钥 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法为聚合名称初始化过滤器 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-initialse-filters-for-aggregation-name-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.1 1. 错误异常的基本描述 # 无法为聚合名称初始化过滤器 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法收集超过指定数量的桶 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/can-t-collect-more-than-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.9-7.15 1. 错误异常的基本描述 # 无法收集超过指定数量的桶 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法解析分片ID 错误的文件夹结构 – 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unable-to-resolve-shard-id-wrong-folder-structure-at-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # 无法解析分片ID 错误的文件夹结构 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法解析证书 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-parse-certificate-s-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.7-8.9 1. 错误异常的基本描述 # 无法解析证书 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返回 400、404、409、429、500 … - [无活动用户 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/no-active-user-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.2-8.9 1. 错误异常的基本描述 # 无活动用户 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返回 400、404、409、429、500 … - [时间点最大保持活跃时间配置](https://easysearch.cn/knowledge-base/easysearch_config/point_in_time.max_keep_alive/): 配置项概述 # point_in_time.max_keep_alive 配置项控制时间点（Point In Time，PIT）上下文的最大保持活跃时间限制。 配置项 默认值 说明 point_in_time.max_keep_alive 24h PIT 最大保持活跃时间 配置说明 # point_in_time.max_keep_alive # 配置项作用： … - [清理 S3 仓库时需要指定区域或端点选项 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/region-or-endpoint-option-is-required-for-cleaning-up-s3-repository-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.4-7.17 1. 错误异常的基本描述 # region or endpoint option is required for cleaning up S3 repository 表示 Elasticsearch 在执行 S3 仓库 cleanup 时，既没有拿到 region，也没有拿到 endpoint。对于 S3 兼容对象存储来说，系统至少需要知道该去哪个区域或哪个服务端 … - [点数不足无法构建线段 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/not-enough-points-to-build-a-line-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.2-8.9 1. 错误异常的基本描述 # 点数不足无法构建线段 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [索引存储预加载配置](https://easysearch.cn/knowledge-base/easysearch_config/config_index.store.preload/): 配置项作用 # index.store.preload 配置项控制在打开索引时预加载哪些扩展名的文件到文件系统缓存。预加载可以加速首次查询性能，但会增加索引打开时间和内存使用。 配置项类型 # 该配置项为静态配置，需要在创建索引时设置。 默认值 # []（空数组，不预加载） 是否必需 # 可选配置项（有默认值） 配置格式 # // 默认配置（不预加载） { … - [缺少名称name的校验和 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/missing-checksum-for-name-name-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # 缺少名称name的校验和 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [网络服务器模式配置](https://easysearch.cn/knowledge-base/easysearch_config/network.server/): 配置项作用 # network.server 配置项用于控制Easysearch 节点是否作为服务器模式运行。 当设置为 true 时，节点会启动服务器端监听端口，允许其他客户端连接；当设置为 false 时，节点不会监听任何端口，只能作为客户端连接到其他节点。 配置项属性 # 配置路径: network.server 数据类型: Boolean（布尔值） 默认值: true 是否可选: … - [节点入站恢复数量配置](https://easysearch.cn/knowledge-base/easysearch_config/cluster.routing.allocation.node_concurrent_incoming_recoveries/): 配置项作用 # cluster.routing.allocation.node_concurrent_incoming_recoveries 配置项控制每个节点上允许同时进行的入站分片恢复操作的最大数量。入站恢复是指节点作为目标节点，从其他节点接收分片数据的过程。 配置项类型 # 该配置项为动态配置，可以在运行时通过集群设置 API 进行修改。 默认值 # 2（ … - [获取集群状态](https://easysearch.cn/knowledge-base/easysearch_api/get-cluster-state/): 获取集群的状态信息，包括元数据、节点信息、路由表、阻塞信息等。 API # GET /_cluster/state GET /_cluster/state/{metric} GET /_cluster/state/{metric}/{indices} API 的作用 # 该 API 用于获取集群的状态信息，可以返回集群的各个方面的状态。 可用的状态指标（metric） # … - [解析字段错误：期望对象但得到其他类型 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/error-parsing-field-name-expected-an-object-but-got-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.16-8.7 1. 错误异常的基本描述 # error parsing field [字段名]; expected an object but got ... 是 Elasticsearch 在解析 range 类型字段 时抛出的映射解析异常。该错误的核心含义是：Elasticsearch 期望该字段的值是一个 JSON 对象（包含 gte、lte、gt、lt 等范围关键字）， … - [设置必须为非负值 SHARED CACHE SETTINGS PREFIX size – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/setting-must-be-non-negative-shared-cache-settings-prefix-size-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.12-8.9 1. 错误异常的基本描述 # 设置必须为非负值 SHARED CACHE SETTINGS PREFIX size 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起 … - [请求超时 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/timeout-request-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 请求超时 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返回 400、404、409、429、500 … - [a positive maxspan value is required found - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/a-positive-maxspan-value-is-required-found-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.8-8.9 1. 错误异常的基本描述 # a positive maxspan value is required; found [value] 是 Elasticsearch 在解析 span query（跨度查询）或 interval query（间隔查询）时抛出的参数验证异常。当你在构造 span 类型的查询（ … - [Aggregator name of type - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/aggregator-name-of-type-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # Aggregator name of type 是 Elasticsearch 在执行聚合（Aggregation）查询时抛出的异常，通常表示某个聚合器的名称或类型定义存在问题，导致 Elasticsearch 无法正确初始化或执行该聚合。 该异常属于查询解析与执行阶段错误，常见于 DSL 构造不规范、聚合类型拼写错误，或使用了当前版 … - [CurrentFieldName 值必须为正数 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/currentfieldname-value-must-be-a-positive-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # CurrentFieldName 值必须为正数 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Easysearch 为什么能“模糊搜索”？原理比你想的简单（和复杂）](https://easysearch.cn/knowledge-base/basic/easysearch-why-fuzzy-search-works-simpler-and-more-complex-than-you-think/): 你是否在搜索框中输入过“苹裹手机”，或者只记得一个词的一部分，比如“华*为”，但 Easysearch 依然能为你找到“苹果手机”和“华为”相关的结果？这种“模糊搜索”的能力，常常让人感到惊奇：搜索引擎是如何理解我的“错别字”或“不完整记忆”的？ 难道它在背后偷偷做了什么“读心术”吗？ 其实，Easysearch 能实现模糊搜索，原理比你想的“更简单”，因为这得益于它底层数据结构和算法的精妙设计； … - [Easysearch 分词是如何影响搜索结果的](https://easysearch.cn/knowledge-base/usage/easysearch-tokenization-impact-on-search-results/): 在构建现代搜索引擎（如 Easysearch 或 Elasticsearch）时，分词（Analysis） 是决定搜索质量的核心环节。很多时候，用户抱怨“搜不到”或者“搜不准”，其根源往往不在于算法模型，而在于底层的分词策略配置不当。 本文将结合官方文档和搜索引擎通用原理，深入探讨 Easysearch 的分词机制，以及它是如何通过影响倒排索引（Inverted Index）来最终左右搜索结果的。 … - [Elasticsearch API 兼容性配置](https://easysearch.cn/knowledge-base/easysearch_config/elasticsearch.api_compatibility/): 配置项概述 # elasticsearch.api_compatibility 配置项控制 Easysearch 是否启用与 Elasticsearch 的 API 兼容模式。 配置项 默认值 说明 elasticsearch.api_compatibility false 启用 ES API 兼容模式 配置说明 # … - [HTTP 服务类型配置](https://easysearch.cn/knowledge-base/easysearch_config/http.type/): 配置项作用 # http.type 配置项指定 HTTP 服务器使用的传输实现类型，决定处理 HTTP 请求的底层网络栈。 是否可选 # 是 默认值 # netty4 配置项类型 # 静态配置 - 需要重启节点才能生效 可用选项 # 类型 说明 适用场景 netty4 Netty4 HTTP 传输（默认） 大多数场景 nio-http-transport Java … - [JVM GC 监控启用配置](https://easysearch.cn/knowledge-base/easysearch_config/monitor.jvm.gc.enabled/): 配置项作用 # monitor.jvm.gc.enabled 配置项控制是否启用 JVM 垃圾回收 (GC) 的监控和统计信息收集。 是否可选 # 是 默认值 # true (启用 GC 监控) 配置项类型 # 动态配置 - 可以在运行时修改 配置格式 # # 启用 GC 监控（默认） monitor.jvm.gc.enabled: true # 禁用 GC … - [Mapping类型名称为空 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/mapping-type-name-is-empty-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # Mapping类型名称为空 表示 Elasticsearch 在校验 mapping type 名称时，发现传入的 type 是空字符串。这个异常多见于 6.x 及更早时期的 typed mapping 接口，或者某些旧客户端、模板生成器在兼容 7.x/8.x 时仍然拼出了空 _type。 常见现象 # 创建索引、 … - [Span first match 必须是 span query 类型 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/span-first-match-must-be-of-type-span-query-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Span first match 必须是 span query 类型 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 … - [Unknown day of week - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unknown-day-of-week-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # unknown day of week 是 Elasticsearch 在解析日期字符串或调度表达式时抛出的异常，表示传入的星期值无法被识别。该异常最常见于以下场景： Watcher 定时调度配置：在 trigger.schedule.weekly 或 cron 表达式中使用了错误的星期值。 日期解析请求： … - [不支持的操作：解析的聚合为空 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unsupported-operation-parsed-aggregations-are-null-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.17 1. 错误异常的基本描述 # 不支持的操作：解析的聚合为空 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [主分片未激活 shards= active= - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/primary-shards-were-not-active-shards-active-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.13-8.9 1. 错误异常的基本描述 # 主分片未激活 shards= active= 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返 … - [允许昂贵查询配置](https://easysearch.cn/knowledge-base/easysearch_config/search.allow_expensive_queries/): 配置项作用 # search.allow_expensive_queries 配置项控制是否允许执行被认为是"昂贵"（expensive）的查询操作。昂贵查询通常指那些可能消耗大量资源（CPU、内存）或执行时间过长的查询类型，如脚本查询、正则表达式查询等。 配置项类型 # 该配置项为动态配置，可以在运行时通过集群设置 API 进行修改。 默认值 # true（允许昂贵查 … - [分片未在恢复状态 (index_shard_not_recovering_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/index_shard_not_recovering_exception/): 为什么这个错误发生 # index_shard_not_recovering_exception 表示尝试对分片执行恢复相关操作，但分片当前不在恢复状态。分片恢复是指将数据从副本或快照恢复到分片的过程。 这个错误可能由以下原因引起： 分片已启动：分片已经完成恢复并启动，不再处于恢复状态 分片未开始恢复：分片尚未开始恢复过程 恢复已完成：恢复操作已经完成 恢复失败：恢复操作失败，分片状态已变更 … - [单节点最大分片数配置](https://easysearch.cn/knowledge-base/easysearch_config/cluster.max_shards_per_node/): 配置项作用 # cluster.max_shards_per_node 配置项限制集群中每个数据节点允许的最大分片数量。当创建索引或打开索引时，系统会检查操作是否会导致集群超过此限制。此限制在分片创建时应用，防止集群因分片过多而变得不稳定。 配置项类型 # 该配置项为动态配置，可以在运行时通过集群设置 API 进行修改。 默认值 # 1000 是否必需 # 可选配置项（有默认值） … - [在等待时遇到意外错误 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/encountered-unexpected-error-while-waiting-for-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # 在等待时遇到意外错误 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [握手超时 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/handshake-timeout-timeout-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 握手超时 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返回 400、404、409、429、500 … - [收到来自较新版本的加入请求——如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/received-a-newer-join-from-how-to-solve-this-elasticsearch-exception/): 适用版本： 7-8.9 1. 错误异常的基本描述 # 收到来自较新版本的加入请求— 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无效的 WKT 格式 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/invalid-wkt-format-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.4-8.9 1. 错误异常的基本描述 # 无效的 WKT 格式 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法对 GEO_POINT 进行取整 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/can-t-round-a-geo-point-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.9-8.9 1. 错误异常的基本描述 # can't round a [GEO_POINT] 是 Elasticsearch 在执行聚合（Aggregation）操作时抛出的异常，表示当前聚合器试图对 geo_point 类型的字段进行"取整（rounding）“操作，但该操作仅适用于数值类型字段，不适用于地理位置类型。 … - [无法将 CA 写入 ZIP 文件 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-write-ca-to-zip-file-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.6-8.9 1. 错误异常的基本描述 # 无法将 CA 写入 ZIP 文件 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法解析仓库不兼容的参数 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-repository-incompatible-params-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # failed to parse repository [{}]; incompatible params 表示 Elasticsearch 在读取 repository 的 settings 字段时，发现它的结构与预期不兼容。结合当前源码片段可以看到，解析器要求 settings 后面必须跟一个对象，也就是 START_OBJECT；如 … - [日志路径配置](https://easysearch.cn/knowledge-base/easysearch_config/path.logs/): 配置项作用 # path.logs 配置项指定 Easysearch 日志文件的存储目录路径。日志文件包括集群运行日志、慢查询日志、访问日志等。 配置项类型 # 该配置项为静态配置，需要在启动时设置，修改后需要重启节点才能生效。 默认值 # $ES_HOME/logs（Easysearch 安装目录下的 logs 文件夹） 是否必需 # 可选配置项（有默认值） 配置格式 # # 默认配 … - [未找到请求用户拥有的ID为id的API密钥 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/no-api-key-owned-by-requesting-user-found-for-id-id-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.5-8.9 1. 错误异常的基本描述 # 未找到请求用户拥有的ID为id的API密钥 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [未知的序列化类型 ord - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unknown-serialized-type-ord-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 未知的序列化类型 ord 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [模板添加未被确认——如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/putting-template-was-not-acknowledged-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-6.8 1. 错误异常的基本描述 # 模板添加未被确认— 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [生成失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-generate-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 生成失败 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返回 400、404、409、429、500 … - [监控批量请求没有正文内容 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/no-body-content-for-monitoring-bulk-request-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 监控批量请求没有正文内容 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [获取集群健康状态](https://easysearch.cn/knowledge-base/easysearch_api/get-cluster-health/): 获取集群的健康状态信息，包括集群状态（GREEN、YELLOW、RED）、分片情况、节点数量等。 API # GET /_cluster/health GET /_cluster/health/{index} API 的作用 # 该 API 用于检查集群的健康状况，返回以下信息： 集群的整体状态（GREEN、YELLOW、RED） 各个索引的健康状态 分片级别的健康信息 各种等待条件的当前状 … - [解析 Action 时无法解析 data attachment 字段 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-action-failed-to-parse-data-attachment-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # could not parse [TYPE] action [watchId/actionId]. failed to parse data attachment field [field] 是 Elasticsearch Watcher 功能在解析 action 配置时抛出的异常。该错误表明 Watcher 已经识别出 action … - [非主分片无法移动到副本——如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/not-primary-can-t-move-to-replica-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 非主分片无法移动到副本— 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [analyzer 和 search_analyzer 配置冲突 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/analyzer-and-search-analyzer-on-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 5.x、6.x、7.x、8.x 1. 错误异常的基本描述 # 在 Elasticsearch 中定义字段映射（mapping）时，如果为某个字段设置了 search_analyzer，但未同时设置 analyzer（即索引分析器），Elasticsearch 会在映射解析阶段抛出 MapperParsingException，报错信息类似： analyzer on field [ … - [can't execute an update request if field or document level security is enabled - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/can-t-execute-an-update-request-if-field-or-document-level-security-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # can't execute an update request if field or document level security is enabled 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定 … - [HipChat 账户的 room 设置数量不符合 profile 要求 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/invalid-hipchat-account-name-room-setting-setting-for-type-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # 在 Elasticsearch Watcher 的 HipChat 通知配置中，如果使用 integration 类型的 profile，则 room 设置只能配置单个值。如果在配置中为该 profile 指定了多个 room（例如写成 YAML 列表或逗号分隔的多值），Elasticsearch 在解析账户配置时会抛出如下异常： … - [HTTP 发布端口配置](https://easysearch.cn/knowledge-base/easysearch_config/http.publish_port/): 配置项作用 # http.publish_port 配置项指定向客户端发布的 HTTP 服务端口号，用于内部端口与外部端口不一致的场景。 是否可选 # 是 默认值 # -1 (自动检测，使用 http.port 的值) 配置项类型 # 静态配置 - 需要重启节点才能生效 配置格式 # # 自动检测（默认） http.publish_port: -1 # NAT … - [Incoming term – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/incoming-term-how-to-solve-this-elasticsearch-exception/): 适用版本： 7-7.15 1. 错误异常的基本描述 # Incoming term 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Parent id 查询不支持 currentFieldName – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/parent-id-query-does-not-support-currentfieldname-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Parent id 查询不支持 currentFieldName 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Span within big 必须是 span 类型查询 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/span-within-big-must-be-of-type-span-query-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Span within big 必须是 span 类型查询 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接 … - [SQL语句过大 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/sql-statement-is-too-large-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # SQL语句过大 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [TCP 接收缓冲区大小配置](https://easysearch.cn/knowledge-base/easysearch_config/network.tcp.receive_buffer_size/): 配置项作用 # network.tcp.receive_buffer_size 配置项用于控制TCP 套接字的接收缓冲区大小。 此配置决定了操作系统为 TCP 连接分配的接收缓冲区大小，影响网络数据的接收性能和内存使用。 配置项属性 # 配置路径: network.tcp.receive_buffer_size 数据类型: ByteSizeValue（字节大小值） 默认值: -1（不设置，使 … - [Warmer 线程池保活时间配置](https://easysearch.cn/knowledge-base/easysearch_config/thread_pool.warmer.keep_alive/): 配置项作用 # thread_pool.warmer.keep_alive 配置项用于控制索引预热线程池中弹性线程的保活时间。 配置项属性 # 配置路径: thread_pool.warmer.keep_alive 数据类型: TimeValue（时间值） 默认值: 5m（5 分钟） 是否可选: 是 作用域: NodeScope（节点级别） 动态更新: 是（可以动态更新，无需重启） 配置建 … - [watch 的 extract 数组必须全部是字符串 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-input-for-watch-expected-a-string-value-in-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.x 1. 错误异常的基本描述 # could not parse [http] input for watch [id]. expected a string value in [field] array; but found [token] instead 表示 Watcher 正在解析 HTTP input 的数组字段，并要求数组成员都是字符串，但实际读到了对象、数 … - [Wrapper Query 格式错误 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/wrapper-query-malformed-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误说明 # [wrapper] query malformed 是 Elasticsearch 在解析 wrapper 查询时抛出的格式异常。该错误表示 wrapper 查询的 JSON 结构在最外层就不符合解析器的预期——解析器进入 wrapper 查询后，期望读取到一个字段名（FIELD_NAME token），但实际读到的 token 类型不匹配，因此 … - [一步步带你搭建第一个 Easysearch 搜索服务](https://easysearch.cn/knowledge-base/basic/step-by-step-guide-to-build-your-first-easysearch-service/): 引言 # 你是否想过在自己的服务器上搭建一个功能强大的中文搜索引擎？比如搜索自己收藏的维基百科、文档库、或者知识库？ 本文将手把手教你用 Python 和 Easysearch 搭建一个支持中文分词的私有维基百科搜索引擎。Easysearch 内置了中文分词的支持，这意味着我们不需要折腾复杂的中文分词配置，直接就能用！ 在文章的最后，你将收获一下如下的私有搜索引擎： $ python3.10 … - [不允许的令牌 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/token-not-allowed-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 不允许的令牌 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返回 400、404、409、429、500 … - [内存映射存储配置](https://easysearch.cn/knowledge-base/easysearch_config/node.store.allow_mmap/): 配置项作用 # node.store.allow_mmap 配置项用于控制是否允许使用内存映射文件（mmap）进行索引存储。 内存映射是一种将文件直接映射到进程虚拟地址空间的技术，可以显著提高文件访问性能。当禁用时，系统将使用 NIOFS 或 SIMPLEFS 等存储类型。 配置项属性 # 配置路径: node.store.allow_mmap 数据类型: Boolean（布尔值） 默认值: … - [创建token时发生ElasticsearchException：未能创建token文档 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/create-token-new-elasticsearchexception-failed-to-create-token-document-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.16-8.11 1. 错误异常的基本描述 # 创建token时发生ElasticsearchException：未能创建token文档 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一 … - [创建默认查询时发生意外错误](https://easysearch.cn/knowledge-base/elasticsearch_error/unexpected-error-creating-default-query-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-6.8 1. 错误异常的基本描述 # 创建默认查询时发生意外错误 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [坐标必须包含至少两个值 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/coordinates-must-contain-at-least-two-values-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.3-8.9 1. 错误异常的基本描述 # 坐标必须包含至少两个值 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [字段 fieldName 不支持 ShapeType MULTIPOINT 查询 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/field-fieldname-does-not-support-shapetype-multipoint-queries-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.16-8.9 1. 错误异常的基本描述 # 字段 fieldName 不支持 ShapeType MULTIPOINT 查询 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判 … - [快照正在进行中 (snapshot_in_progress_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/snapshot_in_progress_exception/): 为什么这个错误发生 # snapshot_in_progress_exception 表示尝试在一个正在进行快照的索引或仓库上执行不允许并发执行的操作。 这个错误可能由以下原因引起： 快照正在执行：快照操作正在进行中 并发快照冲突：尝试同时执行多个快照操作 删除正在快照的索引：尝试删除正在快照的索引 关闭正在快照的索引：尝试关闭正在快照的索引 修改快照中的索引：尝试修改正在快照的索引配置 如 … - [恢复并发操作数配置](https://easysearch.cn/knowledge-base/easysearch_config/indices.recovery.max_concurrent_operations/): 配置项作用 # indices.recovery.max_concurrent_operations 配置项用于控制在索引恢复过程中，源节点到目标节点可以并发发送的操作块（operation chunk）请求的最大数量。 此配置限制并发操作块请求数量，控制恢复过程中的内存使用和网络带宽消耗。 配置项属性 # 配置路径: … - [文档级安全启用时Suggest功能不支持——如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/suggest-isn-t-supported-if-document-level-security-is-enabled-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # 文档级安全启用时Suggest功能不支持— 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法向仓库添加更多快照——如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-add-another-snapshot-to-this-repository-as-it-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.11-7.13 1. 错误异常的基本描述 # Cannot add another snapshot to this repository as it already contains [...] snapshots and is configured to hold up to [...] snapshots only 表示 Elasticsearch 在准备向仓库写入新快照 … - [无法将值从一种类型转换为参数类型 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-cast-value-of-type-to-parameter-type-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.6-7.15 1. 错误异常的基本描述 # 无法将值从一种类型转换为参数类型 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法解析监视器触发事件，日期字段解析失败（Could not parse trigger event for ... failed to parse date field）- 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-trigger-event-for-for-watch-failed-to-parse-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.x 1. 错误异常的基本描述 # could not parse [...] trigger event for [...] for watch [...]. failed to parse date field [...] 表示 Watcher 在解析触发事件中的日期字段时失败了。 从保留代码看，出错字段通常是 triggered_time … - [未知的策略 strategyName - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unknown-strategy-strategyname-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 未知的策略 strategyName 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [构建 ToXContent 失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-build-toxcontent-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Failed to build ToXContent 表示 Elasticsearch 在将某个对象序列化为 XContent（如 JSON、CBOR、YAML 等格式）时失败。该异常通常出现在对象调用 XContentHelper.toXContent(...) 方法的过程中，而不是在请求解析阶段。 结合源码来看， … - [查询仓库（Cat格式）](https://easysearch.cn/knowledge-base/easysearch_api/get-repository-cat-format/): 以紧凑的表格形式返回集群中注册的快照仓库信息。 API 格式 # GET /_cat/repositories API 作用 # 该 API 以表格形式返回快照仓库信息： 显示所有已注册的快照仓库 显示仓库 ID 和类型 快速查看仓库配置概况 API 参数 # 查询参数 # 参数 类型 是否必填 默认值 描述 format String 否 文本表格 响应格式（ … - [模型推理失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-running-inference-on-model-cause-was-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.11-7.15 1. 错误异常的基本描述 # 模型推理失败 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [每节点恢复连接数配置](https://easysearch.cn/knowledge-base/easysearch_config/transport.connections_per_node.recovery/): 配置项作用 # transport.connections_per_node.recovery 配置项控制集群中每个节点之间用于恢复（Recovery）操作的并发连接数。恢复操作包括分片恢复、副本同步等数据传输操作。增加此值可以提高恢复速度，但也会消耗更多资源。 配置项类型 # 该配置项为静态配置，需要在启动时设置，修改后需要重启节点才能生效。 默认值 # 2 是否必需 # 可选配置项（有 … - [用 Easysearch 做实时统计，靠谱吗？](https://easysearch.cn/knowledge-base/usage/easysearch-real-time-statistics-reliability/): 在做数据系统时，“实时统计”几乎是一个绕不开的话题： 页面上的数据要不要立刻更新？ 新写入的数据，统计结果能不能马上看到？ 用搜索引擎直接做实时统计，靠谱么？ Easysearch 作为一款搜索与分析引擎，经常被用于日志分析、监控看板、业务报表等场景。那么问题来了： 用 Easysearch 做实时统计，到底靠不靠谱？ 本文将从 原理、配置和实际可用性 三个层面，给出一个工程化的答案。 … - [角色描述符中的 query 字段解析失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-field-query-from-the-role-descriptor-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.5-8.9 1. 错误异常的基本描述 # 在安全角色描述符中使用 query 限制时，如果模板求值后的内容无法被解析，会报： failed to parse field 'query' from the role descriptor 2. 为什么会发生这个错误 # 源码里会先把角色描述符中的查询模板展开，然后再调用解析与校验逻辑。 … - [解析失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # failed to parse 是 Elasticsearch 中非常典型的一类输入解析异常，表示某个值、字段、参数或 DSL 结构没有按照它预期的格式提供。从当前源码片段看，示例触发点就是在把字符串转换成内部数值时抛出了 ElasticsearchParseException("failed to parse … - [解析点错误 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/error-parsing-point-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.8-8.9 1. 错误异常的基本描述 # 解析点错误 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [连接超时 connectionProfile.getConnectTimeout – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/connect-timeout-connectionprofile-getconnecttimeout-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 连接超时 connectionProfile.getConnectTimeout 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见 … - [concurrent modification of the repository before cleanup started - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/concurrent-modification-of-the-repository-before-cleanup-started-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.4-7.4 1. 错误异常的基本描述 # 仓库清理操作开始前，Elasticsearch 会先读取当前 RepositoryData，并确认仓库 generation 与自己预期的 repositoryStateId 一致。如果发现 generation 已变化，说明在 cleanup 真正开始前，仓库已经被其他操作并发修改，于是抛出 concurrent … - [Easysearch SQL 查询入门](https://easysearch.cn/knowledge-base/basic/easysearch-sql-query-getting-started/): 简介 # 对于许多习惯了传统关系型数据库（RDBMS）的开发者和数据分析师来说，Elasticsearch 强大的 JSON DSL（Domain Specific Language）语法虽然功能丰富，但学习曲线较陡峭。 INFINI Easysearch 作为一款自主可控的分布式近实时搜索与分析引擎，深刻理解用户的这一痛点。它内置了强大的 SQL 支持，允许用户使用标准的 SQL 语法来查询和 … - [Easysearch：自定义 Analyzer，其实没你想的那么难](https://easysearch.cn/knowledge-base/usage/easysearch-custom-analyzer-guide/): 提到 Easysearch（或 Elasticsearch）的 分词器（Analyzer），很多开发者的第一反应是：“我就用默认的 standard，或者装个 ik_max_word，够用就行。” 但当你遇到下面这些场景时，标准分词器往往会让你抓狂： 用户搜邮箱 john.doe@example.com，搜 john 能出，搜 gmail 却出不来？ 搜商品型号 X-2000-Pro， … - [Elasticsearch json 在 5.5.0 版本中已弃用，必须转换为 elasticsearch yml – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/elasticsearch-json-was-deprecated-in-5.5.0-and-must-be-converted-to-elasticsearch-yml-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.1 1. 错误异常的基本描述 # Elasticsearch json 在 5.5.0 版本中已弃用，必须转换为 elasticsearch yml 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日 … - [Elasticsearch yaml 在 5.5.0 版本中已弃用，必须重命名为 elasticsearch.yml – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/elasticsearch-yaml-was-deprecated-in-5.5.0-and-must-be-renamed-to-elasticsearch-yml-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.1 1. 错误异常的基本描述 # Elasticsearch yaml 在 5.5.0 版本中已弃用，必须重命名为 elasticsearch.yml 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合 … - [ID 字段 fielddata 启用配置](https://easysearch.cn/knowledge-base/easysearch_config/indices.id_field_data.enabled/): 配置项作用 # indices.id_field_data.enabled 配置项用于控制是否允许在文档的 _id 字段上加载 fielddata（字段数据）。 当启用时，可以对 _id 字段进行排序和聚合操作；禁用后会阻止在 _id 字段上的 fielddata 访问。 配置项属性 # 配置路径: indices.id_field_data.enabled 数据类型: Boolean（布尔 … - [path [basePath] is not accessible on master node - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/path-basepath-is-not-accessible-on-master-node-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 这条异常出现在仓库校验阶段。Elasticsearch 会在 basePath 下写入一个测试 blob，如果主节点无法完成这一步，就会抛出 RepositoryVerificationException("path ... is not accessible on master node")。 常见现象 # … - [Script Too many dynamic script compilations within max – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/script-too-many-dynamic-script-compilations-within-max-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # Script Too many dynamic script compilations within max 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、 … - [watch 的 input 使用了未知类型 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-input-for-watch-unknown-input-type-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.x 1. 错误异常的基本描述 # could not parse input for watch [id]. unknown input type [type] 表示 Watcher 已经读到了 input 对象里的类型字段名，但在当前节点上找不到与之对应的 InputFactory，因此无法继续构造可执行输入。 这类错误通常发生在 input 第一层类型声明上，常见于 … - [不支持的操作：解析的查询为空 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unsupported-operation-parsed-query-is-null-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.17 1. 错误异常的基本描述 # 不支持的操作：解析的查询为空 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [与远程集群 clusterName 通信时出错 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/error-while-communicating-with-remote-cluster-clustername-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-6.8 1. 错误异常的基本描述 # 与远程集群 clusterName 通信时出错 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [临时索引不应触发存储创建 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/temp-index-should-not-trigger-store-creation-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.8-8.9 1. 错误异常的基本描述 # 临时索引不应触发存储创建 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [主节点选举最大超时配置](https://easysearch.cn/knowledge-base/easysearch_config/cluster.election.max_timeout/): 配置项作用 # cluster.election.max_timeout 配置项控制主节点选举的最大超时时间。这是选举随机延迟时间的上限，即使经过多次退避，选举前的等待时间也不会超过此值。此配置确保在网络分区长时间持续的情况下，一旦分区恢复，能够相对快速地进行选举尝试。 配置项类型 # 该配置项为静态配置，需要在启动时设置，修改后需要重启节点才能生效。 默认值 # 10s 是否必需 # 可 … - [作业调度器线程池大小配置](https://easysearch.cn/knowledge-base/easysearch_config/jobscheduler.threadpool.size/): 配置项作用 # jobscheduler.threadpool.size 配置项用于控制作业调度器线程池的核心线程数量，即同时可以执行的作业调度任务的最大并发数。 此配置决定了作业调度器可以并发处理的任务数量，影响作业调度的吞吐能力和 CPU 资源利用。 配置项属性 # 配置路径: jobscheduler.threadpool.size 数据类型: Integer（整数） 默认值: … - [使 API 密钥失效时出错 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/error-invalidating-api-key-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 使 API 密钥失效时出错 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [删除索引](https://easysearch.cn/knowledge-base/easysearch_api/delete-index/): 删除一个或多个索引，释放集群资源。 API # DELETE /{index} DELETE /* DELETE /_all API 的作用 # 该 API 用于删除索引。删除索引会： 删除索引中的所有文档 删除索引的映射和设置 释放索引占用的磁盘空间 释放索引相关的内存资源 警告：删除操作是不可逆的，请谨慎使用！ API 的参数 # 路由参数 # … - [单播发现主机名解析超时配置](https://easysearch.cn/knowledge-base/easysearch_config/discovery.zen.ping.unicast.hosts.resolve_timeout/): 配置项作用 # discovery.zen.ping.unicast.hosts.resolve_timeout 配置项用于控制在单播发现模式中解析主机名到网络地址时的超时时间。 当使用主机名（而不是 IP 地址）作为种子节点时，系统需要将主机名解析为 IP 地址，此配置决定了这个解析操作的最长等待时间。 配置项属性 # 配置路径: … - [发现带有错误参数的数据框转换持久化任务ID - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/found-data-frame-transform-persistent-task-id-with-incorrect-params-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.2-7.4 1. 错误异常的基本描述 # 发现带有错误参数的数据框转换持久化任务ID 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [在 %s %dms 后超时 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/timed-out-after-s-dms-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.9-8.9 1. 错误异常的基本描述 # 在 %s %dms 后超时 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [应该是哈希类型但实际是其他类型 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/should-be-a-hash-but-was-of-type-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 应该是哈希类型但实际是其他类型 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [引擎提交失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-commit-engine-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 引擎提交失败 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [必须为脚本过滤器提供脚本——如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/script-must-be-provided-with-a-script-filter-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 必须为脚本过滤器提供脚本— 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [搜索请求分片数量限制](https://easysearch.cn/knowledge-base/easysearch_config/action.search.shard_count.limit/): 配置项作用 # action.search.shard_count.limit 配置项限制单次搜索请求最多可以查询的分片数量。该限制旨在防止针对过多分片的大规模搜索请求导致协调节点 CPU 或内存资源耗尽。 配置项类型 # 该配置项为动态配置，可以在运行时通过集群更新 API 进行修改，无需重启节点。 默认值 # Long.MAX_VALUE（9223372036854775807，实际上无 … - [文本或关键字字段无法执行范围查询时 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/range-queries-on-text-or-keyword-fields-cannot-be-executed-when-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.7-7.15 1. 错误异常的基本描述 # 文本或关键字字段无法执行范围查询时 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [文档源缺失 (document_source_missing_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/document_source_missing_exception/): 为什么这个错误发生 # document_source_missing_exception 表示文档存在但其源数据（_source）被禁用或丢失。这通常发生在尝试获取或更新文档的 _source 字段时。 这个错误可能由以下原因引起： _source 被禁用：索引映射中禁用了 _source _source 被过滤：_source 被exclude 配置过滤掉了 文档损坏： … - [无法为特定类型序列化源数据 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-serialize-source-for-type-type-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # 无法为特定类型序列化源数据 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法在只读仓库中创建快照 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-create-snapshot-in-a-readonly-repository-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # cannot create snapshot in a readonly repository 是一个语义非常明确的异常，表示你正在尝试向一个被标记为只读的快照仓库执行写操作。这里的问题不在分片、节点或查询，而在仓库元数据本身。只读仓库允许读取、列出和恢复某些内容，但不允许创建新快照、删除快照或做其他写入型修改。 从当前源码片段可以看 … - [无法解析监视器条件，比较值类型不被当前运算支持（Could not parse condition for watch. compared value for [...] with operation [...] must either be a numeric, string, boolean or null value）- 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-condition-for-watch-compared-value-for-with-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.x 1. 错误异常的基本描述 # could not parse [compare] condition for watch [...]. compared value for [...] with operation [...] must either be a numeric, string, boolean or null value, but found … - [模型ID分配已存在——如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/allocation-for-model-with-id-already-exist-how-to-solve-this-elasticsearch-exception/): 适用版本： 8-8.2 1. 错误异常的基本描述 # 模型ID分配已存在— 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [模型ID的任务分配已存在 – 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/assignment-for-model-with-id-already-exist-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.17-8.9 1. 错误异常的基本描述 # assignment for model with id already exist 是 Elasticsearch 机器学习（Machine Learning）模块中的异常，表示在尝试为某个训练好的模型（Trained Model）创建任务分配（Assignment）时，发现该模型 ID 已经存在对应的分配记录，导致无法重复创建。 … - [由于本地状态不匹配而拒绝请求 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/rejecting-request-since-local-state-is-how-to-solve-this-elasticsearch-exception/): 适用版本： 7-8.9 1. 错误异常的基本描述 # 由于本地状态不匹配而拒绝请求 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [获取映射超时 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/timed-out-getting-mappings-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.1-8.4 1. 错误异常的基本描述 # 获取映射超时 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [解析注释文本时不支持的编码 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unsupported-encoding-parsing-annotated-text-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.17 1. 错误异常的基本描述 # 解析注释文本时不支持的编码 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [跨集群复制跟随者恢复最大并发文件块配置](https://easysearch.cn/knowledge-base/easysearch_config/plugins.replication.follower.index.recovery.max_concurrent_file_chunks/): 配置项作用 # plugins.replication.follower.index.recovery.max_concurrent_file_chunks 配置项用于限制恢复操作期间可处理的最大并发文件块数。 配置项属性 # 配置路径: plugins.replication.follower.index.recovery.max_concurrent_file_chunks 数据类型: … - [阶段失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/phase-failed-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 阶段失败 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返回 400、404、409、429、500 … - [DFS 阶段异常 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/exception-during-dfs-phase-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # DFS 阶段异常 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Easysearch 范围与日期直方图聚合入门指南](https://easysearch.cn/knowledge-base/basic/easysearch-range-date-histogram-aggregation-guide/): 在现代数据分析场景中，从海量数据中快速提取有意义的统计结果，是支撑监控、报表与业务洞察的核心能力。 Easysearch 支持强大的聚合功能，可以对数据按数值范围或时间序列进行分组聚合，从而帮助开发者快速理解数据分布与趋势。 本文重点介绍 Easysearch 中两种常用的 桶聚合 类型： 🎯 范围聚合（range） 📅 日期直方图聚合（date_histogram） 并结合实际示例和可视化实践， … - [Easysearch 运维中最值得关注的日志指标](https://easysearch.cn/knowledge-base/usage/easysearch-operations-important-log-metrics/): 在分布式搜索引擎的运维江湖中，最可怕的不是集群挂了，而是集群变慢了、偶尔报错了，你却不知道为什么。 Easysearch 每天可能会产生数 GB 的日志。对于新手运维来说，这些密密麻麻的文本简直是天书。但对于专家来说，这里面藏着集群健康的“心电图”。 本文将为你剥离噪音，提炼出 Easysearch 运维中最值得关注的四大类日志指标，助你从被动救火转向主动预防。 一、 生命线指标：GC … - [failed to load certificate authorities for PKI realm - PKI Realm 证书颁发机构加载失败](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-load-certificate-authorities-for-pki-realm-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.17（PKI realm 在 8.x 中仍有支持） 1. 错误异常的基本描述 # failed to load certificate authorities for PKI realm 出现在安全模块初始化 PKI realm（Public Key Infrastructure realm，公钥基础设施领域）的过程中。 … - [Headers必须具有值 – 缺少设置fullSetting – 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/headers-must-have-values-missing-for-setting-fullsetting-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.6-8.9 1. 错误异常的基本描述 # Headers必须具有值 – 缺少设置fullSetting 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Hunspell 字典缺少 affix 文件 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/missing-affix-file-for-hunspell-dictionary-s-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # Hunspell 是 Elasticsearch 内置的拼写检查分析器（spell checker analyzer）所依赖的词典引擎。每个 Hunspell 词典目录必须包含两类核心文件： .dic 文件：存放词根和对应词形变化的词典数据 .aff 文件：定义词缀规则（前缀/后缀）的配置文件 当 Elasticsearch 尝试 … - [NAME 没有配置父连接字段 parentJoinField - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/name-no-parent-join-field-parentjoinfield-configured-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.11-8.9 1. 错误异常的基本描述 # NAME 没有配置父连接字段 parentJoinField 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Transform 内部搜索重试延迟配置](https://easysearch.cn/knowledge-base/easysearch_config/transform.internal.search.backoff_millis/): 配置项作用 # transform.internal.search.backoff_millis 配置项用于控制Transform 任务在搜索操作重试之间的延迟时间。 配置项属性 # 配置路径: transform.internal.search.backoff_millis 数据类型: TimeValue（时间值） 默认值: 1000ms（1 秒） 是否可选: 是 作用域: … - [主节点写入存储的文件无法访问 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/a-file-written-by-master-to-the-store-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # a file written by master to the store cannot be accessed on the node 是典型的快照仓库校验异常，含义非常明确：master 节点已经把校验文件写进仓库，但另一个参与校验的节点无法读取这个文件。只要出现这个报错，就几乎可以确认仓库对集群来说不是“统一可见”的，或者节点之 … - [传入的 term applyCommit getTerm 与当前 term 不匹配 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/incoming-term-applycommit-getterm-does-not-match-current-term-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # 传入的 term applyCommit getTerm 与当前 term 不匹配 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判 … - [分片不存在 (shard_not_found_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/shard_not_found_exception/): 为什么这个错误发生 # shard_not_found_exception 表示尝试访问的分片不存在。分片是索引的水平分割单元，当分片不存在时会发生此错误。 这个错误可能由以下原因引起： 分片 ID 错误：请求中指定的分片 ID 不正确 分片未分配：分片已创建但未分配到任何节点 分片已被删除：分片所属的索引被删除或修改 分片正在迁移：分片正在从一个节点迁移到另一个节点 分片状态异常：分片处于初 … - [字段出现未知值 - 可接受的值为 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unknown-value-o-for-field-name-accepted-values-are-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.16-8.6 1. 错误异常的基本描述 # 字段出现未知值 - 可接受的值为 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [客户端传输节点采样间隔配置](https://easysearch.cn/knowledge-base/easysearch_config/client.transport.nodes_sampler_interval/): 配置项作用 # client.transport.nodes_sampler_interval 配置项定义了 TransportClient 节点采样器的执行间隔时间。 节点采样器是 TransportClient 的核心组件，负责： 节点状态监控：定期检查已配置的节点是否存活和可用 节点发现：在嗅探模式下，从集群中发现其他节点 连接管理：自动连接到新增节点，断开不可用的节点连接 集群验证：验 … - [密钥无效主机 host – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/key-invalid-host-host-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.5-8.9 1. 错误异常的基本描述 # 密钥无效主机 host 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [异步搜索持久化结果清理间隔](https://easysearch.cn/knowledge-base/easysearch_config/async_search.expired.persisted_response.cleanup_interval/): 配置项作用 # async_search.expired.persisted_response.cleanup_interval 配置项控制过期异步搜索持久化结果清理任务的运行间隔。该清理任务负责从集群中删除已过期的异步搜索结果数据，释放存储空间。 配置项类型 # 该配置项为静态配置，修改后需要重启节点才能生效。 默认值 # 30m（30分钟） 是否必需 # 可选配置项 取值范围 # … - [文档未找到 index type id – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/document-not-found-index-type-id-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.17 1. 错误异常的基本描述 # 文档未找到 index type id 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法升级索引，因为以下索引缺少主分片 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-upgrade-indices-because-the-following-indices-are-missing-primary-shards-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # 无法升级索引，因为以下索引缺少主分片 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法序列化类型源 root name - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-serialize-source-for-type-root-name-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.14-8.9 1. 错误异常的基本描述 # 无法序列化类型源 root name 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法恢复不兼容的快照 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-restore-incompatible-snapshot-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.3 1. 错误异常的基本描述 # cannot restore incompatible snapshot 表示 Elasticsearch 在真正进入 restore 之前，就已经从 RepositoryData 中判断出该快照属于 incompatibleSnapshotIds，因此直接拒绝恢复并抛出 SnapshotRestoreException。 这类错误不是 … - [无法解析发布地址 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-resolve-publish-address-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 无法解析发布地址 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法解析监视器状态，期望字段是对象（Could not parse watch status. expecting field to be an object）- 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-watch-status-expecting-field-to-be-an-object-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.x 1. 错误异常的基本描述 # could not parse watch status. expecting field [...] to be an object; found [...] instead 表示 Watcher 在解析状态字段时，某个字段必须是 JSON 对象，但实际读到的 token 不是对象。 从保留代码看， … - [日期字段类型不符合解析器预期 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-date-time-expected-date-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # could not parse date/time. expected date field [...] 是 Elasticsearch 在处理日期类型字段时抛出的解析异常。该异常表明日期解析器对某个字段有明确的输入预期，但实际传入的值类型不符合要求，导致解析流程在进入正式日期格式化阶段之前就失败了。 常见现象 # … - [映射器 name 上的未知参数 boost - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unknown-parameter-boost-on-mapper-name-how-to-solve-this-elasticsearch-exception/): 适用版本： 8-8.9 1. 错误异常的基本描述 # 映射器 name 上的未知参数 boost 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [未找到 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/not-found-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.7-8.9 1. 错误异常的基本描述 # 未找到 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返回 400、404、409、429、500 … - [未能获取读取器 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-acquire-reader-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.1-8.9 1. 错误异常的基本描述 # 未能获取读取器 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [第一个对象后的内容格式错误，缺少类型字段 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/malformed-content-after-first-object-either-the-type-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # 第一个对象后的内容格式错误，缺少类型字段 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [获取远程集群信息](https://easysearch.cn/knowledge-base/easysearch_api/get-remote-cluster-info/): 获取已配置的远程集群的信息，包括连接状态、连接模式、代理地址等配置详情。 API # GET /_cluster/remote/info GET /_remote/info API 的作用 # 该 API 用于获取已配置的远程集群的信息。返回每个已配置远程集群的连接详情，包括： 连接状态（connected）：是否已连接 连接模式（mode）：proxy（代理模式）或 sniff（嗅探模式） … - [规则数据库路径配置](https://easysearch.cn/knowledge-base/easysearch_config/ruledb_path.repo/): 配置项作用 # ruledb_path.repo 配置项用于定义规则数据库仓库目录的路径。 配置项属性 # 配置路径: ruledb_path.repo 数据类型: String（字符串路径） 默认值: {pluginsDir}/rules/output_db（插件目录下的 rules/output_db） 是否可选: 是 作用域: NodeScope（节点级别） 动态更新: 是（可以动态更 … - [解析 Email 动作时出现未预期字段 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-email-unexpected-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # could not parse email. unexpected field [field] 表示 Elasticsearch 在解析 Watcher 的 email 动作配置时，遇到了不在当前解析器允许范围内的字段。该异常在 Watcher 执行前就会触发，属于配置解析阶段错误，而非邮件发送阶段的错误。 常见现象 # … - [解析版本设置失败 - 设置值sValue - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-version-setting-setting-with-value-svalue-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # 解析版本设置失败 - 设置值sValue 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [请将 watch 包含字段包装在 watch 字段内 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/please-wrap-watch-including-field-inside-a-watch-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # 请将 watch 包含字段包装在 watch 字段内 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可 … - [读取 indices options 时出现未预期的选项名 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-read-indices-options-unexpected-index-option-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.x-8.x 1. 问题含义 # could not read indices options. unexpected index option [field] 表示 Elasticsearch 正在解析 indices_options 时，遇到了一个不在允许列表内的选项名。 从附带源码可以看出，解析器只接受少量固定字段， … - [跨集群复制领导者线程池大小配置](https://easysearch.cn/knowledge-base/easysearch_config/plugins.replication.leader.thread_pool.size/): 配置项作用 # plugins.replication.leader.thread_pool.size 配置项用于控制领导者复制线程池的线程数量。 配置项属性 # 配置路径: plugins.replication.leader.thread_pool.size 数据类型: Integer（整数） 默认值: 0（自动计算为 (available_processors × 3/2) + 1） … - [远程集群连接开关配置](https://easysearch.cn/knowledge-base/easysearch_config/cluster.remote.connect/): 配置项作用 # cluster.remote.connect 配置项用于控制节点是否支持连接到远程集群。 当设置为 true 时，节点可以与配置的远程集群建立连接，支持跨集群搜索（CCS）功能。当设置为 false 时，节点将不会建立到任何远程集群的连接。 配置项属性 # 配置路径: cluster.remote.connect 数据类型: boolean 默认值: true 是否可选: … - [预期的 FILTER_FIELD getPreferredName 元素 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/expected-filter-field-getpreferredname-element-how-to-solve-this-elasticsearch-exception/): 适用版本： 8-8.9 1. 错误异常的基本描述 # 预期的 FILTER_FIELD getPreferredName 元素 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 … - [Already primary can't move to primary – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/already-primary-can-t-move-to-primary-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Already primary can't move to primary 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 … - [Easysearch 多模态搜索详解：让系统“看懂”图像、“听懂”语音、“理解”文本](https://easysearch.cn/knowledge-base/basic/easysearch-multimodal-search-guide/): 在人工智能快速发展的今天，用户对搜索系统的期待早已超越了“输入关键词、返回文档”的简单模式。越来越多的业务场景中，用户希望用一张图、一段语音、一句话，甚至多种信息组合的方式进行查询——这正是 **多模态搜索（Multimodal Search）**的核心能力。 作为面向企业级应用的分布式搜索引擎，Easysearch 不仅支持传统的全文检索和结构化查询，还深度融合了多模态语义理解能力，帮助企业在图 … - [GeoJSON type 必须是字符串 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/geojson-type-must-be-a-string-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.2-8.2 1. 错误异常的基本描述 # GeoJSON type 必须是字符串 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Path – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/path-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.13 1. 错误异常的基本描述 # Path 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Snapshot 线程池保活时间配置](https://easysearch.cn/knowledge-base/easysearch_config/thread_pool.snapshot.keep_alive/): 配置项作用 # thread_pool.snapshot.keep_alive 配置项用于控制快照线程池中弹性线程的保活时间。 配置项属性 # 配置路径: thread_pool.snapshot.keep_alive 数据类型: TimeValue（时间值） 默认值: 5m（5 分钟） 是否可选: 是 作用域: NodeScope（节点级别） 动态更新: 是（可以动态更新，无需重启） 配 … - [SQL查询](https://easysearch.cn/knowledge-base/easysearch_api/sql-query/): 使用 SQL 语法执行查询操作，对 Easysearch 索引中的数据进行检索和分析。 API 格式 # POST /_sql POST /_sql/_explain API 作用 # 该 API 允许用户使用 SQL 语法查询 Easysearch 索引，支持： 执行 SELECT 查询语句 获取查询执行计划（使用 /_explain 端点） 使用准备语句（Prepared … - [year schedule 的 times 不是对象 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-year-times-expected-an-object-but-found-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # could not parse year times. expected an object; but found [token] 表示 yearly schedule 在解析 times 结构时，期望收到对象，但实际拿到了其他类型。 2. 为什么会发生这个错误 # 源码中的 YearTimes.parse … - [传输层压缩配置](https://easysearch.cn/knowledge-base/easysearch_config/transport.compress/): 配置项作用 # transport.compress 配置项控制集群节点间传输层通信是否启用数据压缩。启用压缩可以减少网络传输的数据量，但会增加 CPU 开销。此配置是已弃用的 transport.tcp.compress 配置的新名称。 配置项类型 # 该配置项为静态配置，需要在启动时设置，修改后需要重启节点才能生效。 默认值 # false（不启用压缩） 是否必需 # 可选配置项（有默 … - [传输层端口配置](https://easysearch.cn/knowledge-base/easysearch_config/transport.port/): 配置项作用 # transport.port 配置项指定 Easysearch 节点间集群内部通信的端口范围。节点通过传输端口进行集群状态同步、分片分配、数据传输等内部操作。 配置项类型 # 该配置项为静态配置，需要在启动时设置，修改后需要重启节点才能生效。 默认值 # 9300-9400 是否必需 # 可选配置项（有默认值） 配置格式 # # 单个端口 transport.port: … - [分片级写入请求数限制配置](https://easysearch.cn/knowledge-base/easysearch_config/cluster.throttle.shard.write.max_requests/): 配置项作用 # 设置分片级别每秒允许的最大写入请求数量。 默认值 # 0（不限制） 配置格式 # # 每秒最多 500 个请求 cluster.throttle.shard.write.max_requests: 500 # 不限制请求数（默认） cluster.throttle.shard.write.max_requests: 0 - [发现两个聚合类型定义 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/found-two-aggregation-type-definitions-in-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # 发现两个聚合类型定义 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [只能在keyword和text字段上使用通配符查询 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/can-only-use-wildcard-queries-on-keyword-and-text-fields-not-on-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.17 1. 错误异常的基本描述 # Can only use wildcard queries on keyword and text fields 是 Elasticsearch 在执行通配符查询（wildcard query）时抛出的异常，表示当前查询目标字段的数据类型不支持通配符查询。 该异常通常发生在查询解析阶段，Elasticsearch 在构建查询计划时发现 … - [字段名不能设置为 index = false – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/the-field-name-cannot-have-index-false-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.9-7.1 1. 错误异常的基本描述 # 字段名不能设置为 index = false 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [字段映射名称同时被定义为对象和字段 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/field-mapper-name-is-defined-both-as-an-object-and-a-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.1-8.9 1. 错误异常的基本描述 # 字段映射名称同时被定义为对象和字段 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [嵌套路径不是嵌套类型——如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/nested-nested-path-path-is-not-nested-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # 嵌套路径不是嵌套类型— 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [延迟重新路由原因失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/delayed-reroute-reason-failed-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.3-8.9 1. 错误异常的基本描述 # 延迟重新路由原因失败 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [快照完成期间集群状态更新失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-update-cluster-state-during-snapshot-finalization-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # Failed to update cluster state during snapshot finalization 表示快照数据本身可能已经写到了仓库，但在“最终把完成结果写回集群状态”这一步失败了。源码里这一段发生在快照收尾逻辑中：如果发现失败与 master failover 有关， … - [执行被取消 (execution_cancelled_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/execution_cancelled_exception/): 为什么这个错误发生 # execution_cancelled_exception 是在执行中的操作被主动取消时抛出的错误。 Easysearch 中的某些长时间运行的操作（如数据恢复、快照创建、批量操作等）是可取消的。当这些操作被系统或用户主动中断时，就会抛出此异常。 这个错误可能由以下原因引起： 用户手动取消：通过 API 手动取消正在执行的任务 节点关闭：节点正在关闭过程中，正在执行的操 … - [排行榜、趋势图，Easysearch 一次查询全搞定](https://easysearch.cn/knowledge-base/usage/easysearch-leaderboard-and-trend-charts/): 在数据统计和可视化场景中，排行榜和趋势图是最常见的图表类型，它们分别用于展示分类排行和时间序列变化。Easysearch 的聚合功能，特别是 date_histogram，能够帮助我们通过一次查询就计算出这些统计结果，并用很少的数据处理工作就绘制出图表。 本文带你从原理到实践逐步掌握如何使用 Easysearch 的 date_histogram 聚合做排行榜和趋势图。 一、Easysearch … - [推理任务因原因 %s 被取消 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/inference-task-cancelled-with-reason-s-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.4-8.9 1. 错误异常的基本描述 # 推理任务因原因 %s 被取消 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无效的状态参数但期望的是另一个值 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/invalid-state-parameter-while-was-expected-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # 无效的状态参数但期望的是另一个值 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法从流中反序列化异常响应 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-deserialize-exception-response-from-stream-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.9 1. 错误异常的基本描述 # 无法从流中反序列化异常响应 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法解析监视器条件，期望路径对象结束（Could not parse condition for watch. expected end of path object）- 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-condition-for-watch-expected-end-of-path-object-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.x 1. 错误异常的基本描述 # could not parse [...] condition for watch [...]. expected end of path object; but found [...] instead 是 Elasticsearch Watcher 功能在解析告警条件（condition）时抛出的异常。该错误表示在解析 compare … - [无法锁定节点目录 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-lock-node-s-directory-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.5 1. 错误异常的基本描述 # 无法锁定节点目录 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [未注册 registryName 的名称 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/no-registryname-registered-for-name-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.17 1. 错误异常的基本描述 # 未注册 registryName 的名称 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [未知的字符串属性 fieldName - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unknown-string-property-fieldname-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 未知的字符串属性 fieldName 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [目标索引必须为小写 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/dest-index-must-be-lowercase-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.3-7.5 1. 错误异常的基本描述 # 目标索引必须为小写 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [索引不存在 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/no-indices-exist-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.2-8.9 1. 错误异常的基本描述 # 索引不存在 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [索引状态管理元数据迁移状态配置](https://easysearch.cn/knowledge-base/easysearch_config/index_state_management.metadata_migration.status/): 配置项作用 # index_state_management.metadata_migration.status 配置项用于跟踪索引状态管理（ISM）的元数据迁移过程状态。 配置项属性 # 配置路径: index_state_management.metadata_migration.status 数据类型: Integer（整数） 默认值: 0（迁移进行中） 是否可选: 是 作用域: … - [获取快照失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-get-snapshots-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 这里的 failed to get snapshots 出现在仓库读取单个 snapshot 元数据的过程中。源码先调用 SNAPSHOT_FORMAT.read(...) 去读快照定义；如果底层抛出 NoSuchFileException，会被转换成更明确的 SnapshotMissingException。 … - [解析 Watch Status 时字段解析失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-watch-status-failed-to-parse-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.1 1. 错误异常的基本描述 # could not parse watch status. failed to parse field [field] 表示 Elasticsearch 在解析 Watch Status 时，某个嵌套字段对象无法被正确解析。该异常通常出现在 Watcher 功能执行过程中，当 Elasticsearch 尝试加载或更新某个 Watch … - [认证令牌OpenID Connect元数据不符合预期 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/in-authentication-token-openid-connect-metadata-is-rather-than-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.2-7.15 1. 错误异常的基本描述 # 认证令牌OpenID Connect元数据不符合预期 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返 … - [配置映射和顶级属性混合 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/mix-of-settings-map-and-top-level-properties-how-to-solve-this-elasticsearch-exception/): 适用版本： 8-8.9 1. 错误异常的基本描述 # 配置映射和顶级属性混合 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [集群选举策略配置](https://easysearch.cn/knowledge-base/easysearch_config/cluster.election.strategy/): 配置项作用 # cluster.election.strategy 配置项用于指定集群主节点选举时使用的策略。选举策略定义了在选举过程中如何判断是否获得足够票数成为主节点的规则。 此配置主要作为插件扩展点，允许通过自定义插件实现特殊的选举约束条件，满足特定的集群部署需求。 配置项类型 # 该配置项为静态配置，需要在 easysearch.yml 配置文件中设置，修改后需要重启节点才能生效。 默 … - [Binary 字段不支持搜索——如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/binary-fields-do-not-support-searching-how-to-solve-this-elasticsearch-exception/): 适用版本： 5.x-8.x（所有版本均不支持 binary 字段搜索） 1. 错误异常的基本描述 # binary fields do not support searching 是 Elasticsearch 在查询执行阶段抛出的 QueryShardException，表示该查询试图对 binary 类型字段进行搜索，但该字段类型在设计上不支持任何查询操作。 错误本质 # Binary … - [cron 数组中没有任何表达式 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-cron-schedule-no-cron-expression-found-in-cron-array-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # could not parse [cron] schedule. no cron expression found in cron array 表示 Watcher 收到了一个 cron 数组，但解析完成后没有拿到任何可用的 cron 表达式。 2. 为什么会发生这个错误 # 源码会先遍历数组，把字符串元素收集到 crons 列表中； … - [date math 不支持该运算符 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/operator-not-supported-for-date-math-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # operator not supported for date math [expr] 是 Elasticsearch 在解析日期数学表达式（Date Math Expression）时抛出的语法异常。该异常表示表达式中出现了 Elasticsearch 日期运算语法不支持的运算符或字符。 日期数学表达式是 Elasticsearch … - [Easysearch 集群中，谁是真正的“控制节点”？](https://easysearch.cn/knowledge-base/usage/easysearch-cluster-control-node-explained/): 在部署 INFINI Easysearch 分布式集群时，初学者往往认为所有节点都是平等的：它们都存储数据，都能响应请求。但实际上，Easysearch 内部有着严格的等级制度和分工。 在一个繁忙的集群中，虽然成百上千个 Data Node（数据节点） 在卖力地搬运数据、执行计算，但真正掌控全局、维持集群秩序的，往往只是背后默默工作的少数几个节点。 今天我们就来揭秘 Easysearch 集群的“ … - [Force Merge 线程池大小配置](https://easysearch.cn/knowledge-base/easysearch_config/thread_pool.force_merge.size/): 配置项作用 # thread_pool.force_merge.size 配置项用于控制强制合并线程池的固定线程数量。 Force Merge 线程池用于执行强制合并操作，减少索引段数量，提高查询性能。 配置项属性 # 配置路径: thread_pool.force_merge.size 数据类型: Integer（整数） 默认值: 1 是否可选: 是 作用域: NodeScope（节点级 … - [JVM GC 开销调试阈值配置](https://easysearch.cn/knowledge-base/easysearch_config/monitor.jvm.gc.overhead.debug/): 配置项作用 # monitor.jvm.gc.overhead.debug 配置项用于控制JVM 垃圾回收（GC）开销的 DEBUG 级别日志阈值。 当 GC 开销（GC 时间占总时间的百分比）达到或超过此阈值时，系统会记录 DEBUG 级别的日志，帮助开发人员分析 GC 行为。 配置项属性 # 配置路径: monitor.jvm.gc.overhead.debug 数据类型: … - [Script score脚本无法加载——如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/script-score-the-script-could-not-be-loaded-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Script score脚本无法加载— 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Translog 看起来像版本1或更高版本但头部损坏 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/translog-looks-like-version-1-or-later-but-has-corrupted-header-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.16-8.5 1. 错误异常的基本描述 # Translog 看起来像版本1或更高版本但头部损坏 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接 … - [Unknown field found - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unknown-field-found-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误说明 # unknown field found 是 Elasticsearch 在解析请求体（JSON）时抛出的 ParsingException。当 Elasticsearch 的 XContentParser 处于严格解析模式时，如果请求体中包含了当前 API 或对象结构未定义的字段，就会触发此异常并拒绝整个请求。 … - [Unknown object property [fieldName] - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unknown-object-property-fieldname-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # unknown object property [fieldName] 表示 Elasticsearch 在解析对象时，遇到了不在预期属性列表中的字段。 从源码可见，这个异常在 XContentParser 解析对象属性的路径中抛出，当属性名无法匹配任何已知的解析分支时触发。它强调的是 对象里的字段名不合法，而不是字段后的值类型不对。 … - [不支持进程关系 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/process-relationships-are-not-supported-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.16-8.9 1. 错误异常的基本描述 # 不支持进程关系 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [事务日志被截断 - 如何解决此Easticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/translog-truncated-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 事务日志被截断 - 如何解决此Easticsearch异常 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [仅在未进行重新配置时才允许重新配置——如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/only-allow-reconfiguration-while-not-already-reconfiguring-how-to-solve-this-elasticsearch-exception/): 适用版本： 7-8.9 1. 错误异常的基本描述 # 仅在未进行重新配置时才允许重新配置— 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [从集群状态删除快照失败 – 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-remove-snapshot-from-cluster-state-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.7-8.9 1. 错误异常的基本描述 # Failed to remove snapshot from cluster state 表示快照删除流程已经推进到主节点更新 cluster state 的阶段，但在移除快照元数据、通知监听器或发布新的集群状态时失败。根据源码，这类失败会包装成 SnapshotException，并伴随 completion listener … - [分片分配器类型配置](https://easysearch.cn/knowledge-base/easysearch_config/cluster.routing.allocation.type/): 配置项作用 # cluster.routing.allocation.type 配置项指定分片分配器（Shards Allocator）的类型，决定集群如何将分片分配到各个节点上。不同的分配器使用不同的算法来实现负载均衡。 配置项类型 # 该配置项为静态配置，需要在启动时设置，修改后需要重启节点才能生效。 默认值 # balanced（平衡分配器） 是否必需 # 可选配置项 配置值说明 # … - [分片分配感知属性配置](https://easysearch.cn/knowledge-base/easysearch_config/cluster.routing.allocation.awareness.attributes/): 配置项作用 # cluster.routing.allocation.awareness.attributes 配置项用于启用分片分配感知（Allocation Awareness）功能。通过感知节点的物理或逻辑属性（如机架、可用区、数据中心等），确保分片尽可能均匀地分布到不同的故障域，提高集群的容错能力。 配置项类型 # 该配置项为动态配置，可以在运行时通过集群设置 API 进行修改。 默认 … - [分片必须具有有效的事务日志生成号和UUID，但获取到的是 – 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/shard-must-have-a-valid-translog-generation-and-uuid-but-got-and-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.6 1. 错误异常的基本描述 # 分片必须具有有效的事务日志生成号和UUID，但获取到的是 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [创建密码器错误 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/error-creating-cipher-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 创建密码器错误 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [字段无效的星期值，期望字符串/数字值或数组 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/invalid-week-day-value-for-field-expected-string-number-value-or-an-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # 字段无效的星期值，期望字符串/数字值或数组 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [字段月份日值无效，期望字符串或数值——如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/invalid-month-day-value-for-field-expected-string-number-value-or-an-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # 字段月份日值无效，期望字符串或数值— 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [存储字段在请求源字段时不能禁用 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/stored-fields-cannot-be-disabled-if-source-is-requested-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 存储字段在请求源字段时不能禁用 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [当 OLAP 遇到搜索：Easysearch vs Doris 倒排索引实现深度剖析](https://easysearch.cn/knowledge-base/basic/easysearch-vs-doris-inverted-index-deep-dive/): 本文基于 2026-01-30 的最新 commit 和版本： Doris Commit: 4a37aec7d25362a91f Doris Clucene commit: ac9475a6a61d371 当 OLAP 遇到搜索：Easysearch vs. Doris 倒排索引实现深度剖析 # 在数据技术融合的今天，我们看到一个有趣的趋势：OLAP（在线分析处理）引擎正在集成搜索引擎的能 … - [搜索上下文最大保活时间配置](https://easysearch.cn/knowledge-base/easysearch_config/search.max_keep_alive/): 配置项作用 # search.max_keep_alive 配置项控制滚动搜索上下文（Scroll Context）的最大保活时间。滚动搜索允许客户端分批获取大量结果集，此配置限制一个滚动上下文可以保持活跃的最大时间。 配置项类型 # 该配置项为动态配置，可以在运行时通过集群设置 API 进行修改。 默认值 # 24h 是否必需 # 可选配置项（有默认值） 取值范围 # 0 ~ 正无穷 … - [无法使用 PBKDF2 进行密码哈希处理 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/can-t-use-pbkdf2-for-password-hashing-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.1 1. 错误异常的基本描述 # 无法使用 PBKDF2 进行密码哈希处理 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法自动解析发布端口 - 多个绑定地址导致Elasticsearch异常及解决方案](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-auto-resolve-publish-port-profileexplanation-multiple-bound-addresses-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # 无法自动解析发布端口 - 多个绑定地址导致Elasticsearch异常及解决方案 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 … - [无法解析 cron schedule - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-cron-schedule-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # could not parse [cron] schedule 是 Elasticsearch Watcher 中 cron 调度解析失败的通用包装异常。当你在配置 Watcher 的定时触发器的 cron 表达式时，如果表达式文本不符合 Watcher 内部 CronSchedule 的语法规范，就会抛出此异常。 常见现象 # 创 … - [标记仓库状态为损坏失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-marking-repository-state-as-corrupted-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.6-7.13 1. 错误异常的基本描述 # Failed marking repository state as corrupted 表示 Elasticsearch 在检测到仓库异常之后，尝试把 repository state 标记为损坏时又发生了第二次失败。根据当前源码片段，这一步通常是通过 cluster state update 将仓库 generation … - [生成密钥失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-generate-key-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 生成密钥失败 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [禁止创建动态嵌套对象——如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/it-is-forbidden-to-create-dynamic-nested-objects-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # 禁止创建动态嵌套对象— 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [聚合执行异常 (aggregation_execution_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/aggregation_execution_exception/): 为什么这个错误发生 # aggregation_execution_exception 表示在执行聚合查询时发生错误。聚合用于对搜索结果进行统计分析，如求和、平均值、分组等。 这个错误可能由以下原因引起： 字段类型错误：聚合字段的数据类型不支持该聚合类型 字段不存在：聚合引用的字段不存在 映射冲突：字段映射与聚合操作不兼容 桶数量过多：聚合产生的桶数量超过限制 深度嵌套：聚合嵌套层级过深 脚本 … - [获取网站图标](https://easysearch.cn/knowledge-base/easysearch_api/get-site-icon/): 此 API 用于返回 Easysearch 的网站图标（favicon）。 API # GET /favicon.ico API 的作用 # 返回 Easysearch 的网站图标文件。这是浏览器在显示网站标签页时会请求的标准图标文件。 API 的参数 # 此 API 没有路由参数和查询字符串参数。 响应信息 # 状态码：200 OK Content-Type：image/x-icon … - [解析 Watch Input 时该内容类型不支持 key extraction - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-input-for-watch-key-extraction-is-not-supported-for-content-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # could not parse [TYPE] input for watch [watchId]. key extraction is not supported for content type [contentType] 表示在解析 Watcher 的 HTTP Input 时，当前配置的内容类型（Content Type） … - [解析记录失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-records-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 解析记录失败 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [跨集群复制自动跟随并发触发大小配置](https://easysearch.cn/knowledge-base/easysearch_config/replication.autofollow.concurrent_replication_jobs_trigger_size/): 配置项作用 # replication.autofollow.concurrent_replication_jobs_trigger_size 配置项用于控制触发自动跟随复制任务的并发任务数量。 配置项属性 # 配置路径: replication.autofollow.concurrent_replication_jobs_trigger_size 数据类型: Integer（整数） 默认 … - [运行时字段上的 PropName 错误 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/propname-on-runtime-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.14-7.15 1. 错误异常的基本描述 # 运行时字段上的 PropName 错误 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [重建索引时发生错误：批量失败和搜索失败 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/error-occurred-while-reindexing-bulk-failures-search-failures-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-6.8 1. 错误异常的基本描述 # 重建索引时发生错误：批量失败和搜索失败 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [analysis failed - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/analysis-failed-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误说明 # analysis failed 表示 Elasticsearch 在文本分析（analysis）阶段发生了异常。文本分析是 Elasticsearch 处理文本字段的核心环节，发生在： 索引时：对 text 类型字段进行分词、归一化，生成倒排索引 查询时：对 match、match_phrase 等全文查询中的查询字符串进行分词 当分析器配置 … - [Count必须是路径中的最后一个元素 – 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/count-must-be-the-last-element-in-the-path-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # Count必须是路径中的最后一个元素 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [fetch fields 参数出现意外的值 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unexpected-value-v-for-fetch-fields-parameter-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.2-8.9 1. 错误异常的基本描述 # fetch fields 参数出现意外的值 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Flush 线程池核心大小配置](https://easysearch.cn/knowledge-base/easysearch_config/thread_pool.flush.core/): 配置项作用 # thread_pool.flush.core 配置项用于控制索引刷新线程池的核心线程数。 Flush 线程池用于执行索引刷新操作，将内存中的索引数据写入磁盘，确保持久化。 配置项属性 # 配置路径: thread_pool.flush.core 数据类型: Integer（整数） 默认值: 1 是否可选: 是 作用域: NodeScope（节点级别） 动态更新: 是（可以动态 … - [include/exclude 子句中缺少数组开始标记 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/missing-start-of-array-in-include-exclude-clause-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # include/exclude 子句中缺少数组开始标记 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可 … - [NAME unknown token – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/name-unknown-token-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # [NAME] unknown token [token] after [currentFieldName] 表示某个查询构建器在解析 DSL 时，已经识别出当前字段名，但字段后面跟着的 JSON token 类型不合法。 这里的 NAME 是源码里的占位常量，不代表具体就是字符串 NAME。真正触发时，报错通常会变成某个具体查询名，比 … - [No longer master source source – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/no-longer-master-source-source-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.2 1. 错误异常的基本描述 # No longer master source source 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可 … - [Node nodes – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/node-nodes-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.12-7.15 1. 错误异常的基本描述 # Node nodes 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [PIVOT 当前仅支持一个聚合发现 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/pivot-currently-supports-only-one-aggregation-found-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.5-7.15 1. 错误异常的基本描述 # PIVOT 当前仅支持一个聚合发现 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Required - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/required-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.3-8.9 1. 错误异常的基本描述 # Required 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Search 线程池目标响应时间配置](https://easysearch.cn/knowledge-base/easysearch_config/thread_pool.search.target_response_time/): 配置项作用 # thread_pool.search.target_response_time 配置项用于控制搜索操作的目标响应时间。 这是用于基于 Little’s Law 自动调整队列大小时的参考目标。 配置项属性 # 配置路径: thread_pool.search.target_response_time 数据类型: TimeValue（时间值） 默认值: 1s（1 秒） … - [Span near 必须包含 clauses 子句 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/span-near-must-include-clauses-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Span near 必须包含 clauses 子句 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返 … - [TCP 连接超时配置](https://easysearch.cn/knowledge-base/easysearch_config/network.tcp.connect_timeout/): 配置项作用 # network.tcp.connect_timeout 配置项用于控制建立 TCP 连接时的最大等待时间。 此配置决定了 Easysearch 在等待 TCP 连接建立完成时最多等待多长时间，超时后将放弃连接尝试。 配置项属性 # 配置路径: network.tcp.connect_timeout 数据类型: TimeValue（时间值） 默认值: 30s（30秒） 最小值: … - [Unable to check if bucket [bucketName] exists - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unable-to-check-if-bucket-bucketname-exists-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.8 1. 错误异常的基本描述 # 这条异常说明 Elasticsearch 不是确认 bucket 不存在，而是“连 bucket 是否存在都检查失败”。源码在 doesBucketExist() 捕获任意异常后，统一抛出 BlobStoreException("Unable to check if bucket [...] exists", e)。 … - [Unknown function - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unknown-function-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # unknown function 是 Elasticsearch SQL 模块在解析 SQL 查询时抛出的 ParsingException 异常，表示当前查询中使用了 Elasticsearch 无法识别的函数名称。该异常通常发生在 SQL 解析阶段，在查询真正执行之前就会失败，因此不会触发数据扫描或计算结果。 … - [不能同时使用 sort 和 rescore - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-use-sort-option-in-conjunction-with-rescore-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-6.8 1. 错误异常的基本描述 # 查询同时包含显式排序和重排配置时，Elasticsearch 会抛出： Cannot use [sort] option in conjunction with [rescore]. 很多时候这会表现为搜索请求直接失败，尤其是在应用层把“业务排序”和“精排”两个模块拼到同一条 DSL 时。 2. 为什么会发生这个错误 # … - [为字段添加度量时出错 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/error-while-adding-metric-for-field-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.4-8.9 1. 错误异常的基本描述 # 为字段添加度量时出错 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [分片不处于主模式异常 (shard_not_in_primary_mode_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/shard_not_in_primary_mode_exception/): 为什么这个错误发生 # shard_not_in_primary_mode_exception 表示分片当前不处于主模式（primary mode），但操作要求分片必须是主分片。这通常发生在尝试对副本分片执行只有主分片才能执行的操作时。 这个错误可能由以下原因引起： 分片是副本：操作针对的是副本分片而非主分片 主分片迁移中：主分片正在迁移到其他节点 分片恢复中：分片正在恢复过程中 分片状态转 … - [创建信任管理器失败 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-create-trust-manager-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # 创建信任管理器失败 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [副本在 Easysearch 中承担的不只是高可用](https://easysearch.cn/knowledge-base/usage/easysearch-replicas-more-than-high-availability/): 在许多用户的认知中，副本（Replica）仅仅是数据的“备胎”，用于防止节点故障导致的数据丢失。然而在 Easysearch 的分布式架构中，副本更是提升查询吞吐量（QPS）和应对高并发读取的“扩音器”。本文将深度解析副本如何通过负载均衡机制加速读取，以及如何平衡副本带来的存储成本与性能收益。 当我们创建一个 Easysearch 索引时，通常会看到配置 number_of_replicas: … - [向量检索 vs 关键词检索：Easysearch 如何同时支持两种搜索能力](https://easysearch.cn/knowledge-base/basic/vector-search-vs-keyword-search-easysearch-guide/): 在现代搜索系统里，单纯的关键词匹配已经无法满足用户对 **语义理解 **和 **个性化搜索体验 **的需求。为了让搜索更智能、更贴近用户意图，越来越多的系统开始引入 向量检索。而市场上成熟的搜索引擎仍然离不开 关键词检索 的稳定基础。那么，什么是向量检索和关键词检索？它们有什么区别？Easysearch 又是如何在一个系统中同时支持这两种搜索方式的？我们从核心原理出发，用通俗的语言来解释这些问题。 … - [坐标不能指定为对象 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/coordinates-cannot-be-specified-as-objects-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 坐标不能指定为对象 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [字段格式已更改 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/fields-format-has-changed-for-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # 字段格式已更改 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [导入规则库（自动ID追加）](https://easysearch.cn/knowledge-base/easysearch_api/import-ruleset-auto-id-append/): 自动生成规则库 ID 并导入规则，使用追加模式。如果同 ID 的规则库已存在，将追加规则；否则创建新规则库。 API 格式 # PUT /_match_rules/_import API 作用 # 该 API 用于自动生成规则库 ID 并导入规则： 自动生成 ID：系统自动生成格式为 repo_<timestamp> 的规则库 ID 追加模式：如果规则库已存在，追加新规则；否则创 … - [批量请求执行失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/bulk-request-execution-failure-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.5-8.9 1. 错误异常的基本描述 # 批量请求执行失败 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [指定的连接键数量不一致：期望但实际找到——如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/inconsistent-number-of-join-keys-specified-expected-but-found-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.8-7.15 1. 错误异常的基本描述 # 指定的连接键数量不一致：期望但实际找到— 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法注册节点 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unable-to-enroll-node-how-to-solve-this-elasticsearch-exception/): 适用版本： 8-8.9 1. 错误异常的基本描述 # 无法注册节点 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返回 400、404、409、429、500 … - [期望至少一个上下文映射 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/expected-at-least-one-context-mapping-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 期望至少一个上下文映射 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [脚本编译速率限制配置](https://easysearch.cn/knowledge-base/easysearch_config/script.max_compilations_rate/): 配置项作用 # script.max_compilations_rate 配置项控制在指定时间内允许编译的脚本数量限制。此配置用于防止过多的脚本编译操作消耗过多 CPU 资源，保护系统稳定性。 配置项类型 # 该配置项为动态配置，可以在运行时通过集群设置 API 进行修改。 默认值 # use-context（根据脚本上下文自动调整） 是否必需 # 可选配置项（有默认值） 取值范围 # … - [获取分片锁超时 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/timed-out-while-waiting-to-acquire-shard-lock-for-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.7-8.9 1. 错误异常的基本描述 # 获取分片锁超时 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [问答结果无数据 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/question-answering-result-has-no-data-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.3-8.9 1. 错误异常的基本描述 # 问答结果无数据 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [限流搜索线程池大小配置](https://easysearch.cn/knowledge-base/easysearch_config/thread_pool.search_throttled.size/): 配置项作用 # thread_pool.search_throttled.size 配置项用于控制限流搜索线程池的线程数量。 当索引被标记为 index.search.throttled=true 时，该索引的搜索请求会被路由到此线程池处理。 配置项属性 # 配置路径: thread_pool.search_throttled.size 数据类型: Integer（整数） 默认值: 1 是否 … - [集群状态发布信息日志超时配置](https://easysearch.cn/knowledge-base/easysearch_config/cluster.publish.info_timeout/): 配置项作用 # cluster.publish.info_timeout 配置项控制集群状态发布操作在记录 INFO 级别日志前的等待时间。当集群状态发布耗时超过此配置值时，会记录一条 INFO 级别的日志，提示集群状态发布较慢。此配置用于监控集群状态发布的性能。 配置项类型 # 该配置项为静态配置，需要在启动时设置，修改后需要重启节点才能生效。 默认值 # 10s 是否必需 # 可选配置 … - [Extended bounds min 不能大于 max 值 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/extended-bounds-min-min-cannot-be-greater-than-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.4 1. 错误异常的基本描述 # Extended bounds min 不能大于 max 值 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [include_in_parent 参数无法在嵌套对象映射上更新 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/the-include-in-parent-parameter-can-t-be-updated-on-a-nested-object-mapping-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.9-8.9 1. 错误异常的基本描述 # include_in_parent 参数无法在嵌套对象映射上更新 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Lucene 与 Elasticsearch、Easysearch：引擎与分布式架构概览](https://easysearch.cn/knowledge-base/basic/lucene-elasticsearch-easysearch-distributed-architecture/): Elasticsearch 与 Easysearch 都是基于 Lucene 的分布式搜索与分析引擎。如果把它们比作一辆汽车，那么 Lucene 就是发动机。当你开车时并不直接操作发动机，但当汽车出现故障时，理解发动机的工作原理会极大提升排障效率。 与 Elasticsearch 类似，Apache Solr 的核心思想也是在 Lucene 之上构建分布式搜索系统（Solr … - [request body or source parameter is required - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/request-body-or-source-parameter-is-required-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 这条异常比 request body is required 更具体。contentOrSourceParam() 会先检查请求是否包含 body 或 source 参数，只要两者都没有，就抛出 ElasticsearchParseException("request body or source parameter is … - [Rollup 仪表板功能配置](https://easysearch.cn/knowledge-base/easysearch_config/rollup.dashboards.enabled/): 配置项作用 # rollup.dashboards.enabled 配置项用于控制是否启用 Rollup 索引的仪表板字段映射支持。 当启用时，系统会拦截字段能力请求并重写响应，包含 Rollup 索引的字段映射信息，使 Kibana 等 Dashboard 工具能正确显示 Rollup 索引的字段类型。 配置项属性 # 配置路径: rollup.dashboards.enabled 数据类 … - [SimpleQueryStringBuilder NAME 分析器 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/simplequerystringbuilder-name-analyzer-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # SimpleQueryStringBuilder NAME 分析器 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 … - [X Pack is not supported and Machine Learning is not available for - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/x-pack-is-not-supported-and-machine-learning-is-not-available-for-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # X Pack is not supported and Machine Learning is not available for 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面 … - [创建的 bucket 数量超过上限 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/trying-to-create-too-many-buckets-must-be-less-than-or-equal-to-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.15 1. 错误异常的基本描述 # Trying to create too many buckets. Must be less than or equal to: [limit] but was [count] 表示 Elasticsearch 在聚合执行过程中累计创建的 bucket 数量超过了集群级动态设置 search.max_buckets 的阈值， … - [处理 ping 时发生未知错误 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unknown-error-while-processing-ping-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.17 1. 错误异常的基本描述 # 处理 ping 时发生未知错误 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [大小写不敏感的term查询 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/case-insensitive-term-query-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.3-8.9 1. 错误异常的基本描述 # 大小写不敏感的term查询 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [字段解析 null 值错误 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/error-parsing-null-value-on-field-name-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.1-8.9 1. 错误异常的基本描述 # 字段解析 null 值错误 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [存储的任务状态不包含任何源信息 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/stored-task-status-for-didn-t-contain-any-source-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 存储的任务状态不包含任何源信息 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [存储脚本ID不存在且无法删除 – 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/stored-script-id-does-not-exist-and-cannot-be-deleted-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 存储脚本ID不存在且无法删除 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [客户端传输集群名称验证配置](https://easysearch.cn/knowledge-base/easysearch_config/client.transport.ignore_cluster_name/): 配置项作用 # client.transport.ignore_cluster_name 配置项用于控制 TransportClient 在连接到集群节点时是否验证集群名称。 TransportClient 是 Easysearch 提供的 Java 客户端，它通过传输协议直接与集群节点通信。当客户端连接到节点时，默认情况下会验证节点的集群名称是否与客户端配置的集群名称一致，这是一种安全保护机 … - [客户端类型配置](https://easysearch.cn/knowledge-base/easysearch_config/client.type/): 配置项作用 # client.type 配置项指定 Easysearch 客户端的类型，决定客户端与集群的连接方式和行为模式。 配置项类型 # 该配置项为静态配置，需要在启动时设置，修改后需要重启节点才能生效。 默认值 # node 是否必需 # 可选配置项 配置值说明 # 值 说明 node 节点客户端（默认） transport 传输客户端 客户端类型详解 # … - [必须是有效的双精度浮点值 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/must-be-a-valid-double-value-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.2-8.9 1. 错误异常的基本描述 # 必须是有效的双精度浮点值 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [快照失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-snapshot-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.4 1. 错误异常的基本描述 # Failed to snapshot 表示 Elasticsearch 在执行 shard 级 snapshot 时捕获到了一个未被 SnapshotFailedEngineException 或已有 IndexShardSnapshotFailedException 覆盖的其他异常， … - [意外的字段名预期 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unexpected-field-name-expected-how-to-solve-this-elasticsearch-exception/): 适用版本： 7-7.15 1. 错误异常的基本描述 # 意外的字段名预期 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [折叠字段无法展开 inner_hits - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-expand-inner-hits-for-collapse-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.4 1. 错误异常的基本描述 # 使用字段折叠时，如果还配置了 inner_hits，但折叠字段本身不可索引，查询会报错： cannot expand `inner_hits` for collapse field `field`; only indexed field can retrieve `inner_hits` 这意味着折叠本身可能能通过， … - [数据存储路径配置](https://easysearch.cn/knowledge-base/easysearch_config/path.data/): 配置项作用 # path.data 配置项指定 Easysearch 存储数据文件的目录路径。数据文件包括索引数据、分片数据、事务日志等所有持久化数据。 配置项类型 # 该配置项为静态配置，需要在启动时设置，修改后需要重启节点才能生效。 默认值 # $ES_HOME/data（Easysearch 安装目录下的 data 文件夹） 是否必需 # 可选配置项（有默认值，但生产环境强烈建议配 … - [无效值错误 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/invalid-value-for-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.2-8.9 1. 错误异常的基本描述 # 无效值错误 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返回 400、404、409、429、500 … - [无法关联新的事务日志 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-associate-a-new-translog-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.8-8 1. 错误异常的基本描述 # 无法关联新的事务日志 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法执行操作，因为配置暂时处于迁移状态 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-as-the-configuration-is-temporarily-pending-migration-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # 无法执行操作，因为配置暂时处于迁移状态 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法解析浮点设置 setting 的值 sValue – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-float-setting-setting-with-value-svalue-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 无法解析浮点设置 setting 的值 sValue 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能 … - [无法解析监视器执行请求（Could not parse watch execution request）- 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-watch-execution-request-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.x 1. 错误异常的基本描述 # could not parse watch execution request 表示 Elasticsearch 在解析 Watcher 的执行请求体时失败了。它不是执行阶段错误，而是请求还没有被正确构造成内部对象之前，就因为字段名、字段类型或字段值不符合预期而被拒绝。 常见现象 # … - [暂停跟随请求未被确认 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/pause-follow-request-failed-to-be-acknowledged-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.12-8.9 1. 错误异常的基本描述 # 暂停跟随请求未被确认 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [期望长度为 2 的双精度数组 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/expected-double-array-of-length-2-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-6.8 1. 错误异常的基本描述 # 期望长度为 2 的双精度数组 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [未找到与请求名称匹配的数据流 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/data-streams-matching-request-name-not-found-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.9-8.11 1. 错误异常的基本描述 # 未找到与请求名称匹配的数据流 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [查询脚本上下文](https://easysearch.cn/knowledge-base/easysearch_api/get-script-context/): 此 API 用于获取 Easysearch 中所有可用的脚本上下文（Script Contexts）信息。脚本上下文定义了脚本可以在哪些场景中使用以及可以使用哪些功能。 API # GET /_script_context API 的作用 # 返回所有可用的脚本上下文信息，包括每个上下文的名称、方法以及方法的参数信息。这对于开发者了解在脚本中可以使用哪些上下文和功能非常有用。 脚本上下文定义了 … - [策略已存在 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/policy-already-exists-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.5-8.9 1. 错误异常的基本描述 # 策略已存在 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [索引模板不存在 (index_template_missing_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/index_template_missing_exception/): 为什么这个错误发生 # index_template_missing_exception 表示请求的索引模板不存在。 如何修复 # 1. 列出所有模板 # GET /_index_template/* GET /_cat/templates?v 2. 创建模板 # PUT /_index_template/<template_name> { … - [节点没有索引的元数据 – 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/node-doesn-t-have-meta-data-for-index-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.6-8.9 1. 错误异常的基本描述 # 节点没有索引的元数据 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [资源重载启用配置](https://easysearch.cn/knowledge-base/easysearch_config/resource.reload.enabled/): 配置项作用 # resource.reload.enabled 配置项控制资源监控服务的启用状态。 默认值 # true 配置类型 # 静态配置 配置格式 # # 默认配置 resource.reload.enabled: true - [错误前缀长度不匹配问题 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/too-errorprefix-lowercase-length-36-long-short-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 错误前缀长度不匹配问题 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [集群发现种子提供者配置](https://easysearch.cn/knowledge-base/easysearch_config/discovery.seed_providers/): 配置项作用 # discovery.seed_providers 配置项用于指定集群发现过程中使用的**种子主机提供者（Seed Hosts Providers）**列表。 种子提供者负责为集群提供初始节点地址信息，使节点能够发现并加入集群。 配置项属性 # 配置路径: discovery.seed_providers 数据类型: list（字符串列表） 默认值: []（空列表， … - [集群变黄、变红时，你第一步该看什么](https://easysearch.cn/knowledge-base/usage/easysearch-cluster-yellow-red-first-steps/): 当监控报警响起，Easysearch 集群状态变为 Yellow 或 Red 时，盲目重启节点往往不仅无济于事，甚至会加重故障。本文将提供一套标准化的排查“三板斧”，教你如何利用 _cluster/health、_cat/shards 和 allocation/explain 三个核心 API，在 5 分钟内精准定位故障根因。 对于 Easysearch 管理员来说，最不想看到的颜色就是红色。 … - [analytics collection already exists - Analytics Collection 已存在如何解决](https://easysearch.cn/knowledge-base/elasticsearch_error/analytics-collection-already-exists-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.8-8.9 1. 错误异常的基本描述 # analytics collection already exists 表示在 Elasticsearch 中创建 Analytics Collection（分析集合）时，同名资源已经存在，导致创建操作失败。这是一个典型的资源冲突异常，底层由 ResourceAlreadyExistsException 触发。 常见现象 # … - [Easysearch 中文分词实战：IK 分词器配置与优化](https://easysearch.cn/knowledge-base/usage/easysearch-chinese-word-segmentation-ik-analyzer/): 在中文搜索领域，“分词（Tokenization）”是决定搜索质量的基石。不同于英文单词之间有天然的空格分隔，中文必须通过算法将连续的字符串切分成有意义的词汇。 IK Analysis 是目前 Elasticsearch 生态中最流行、最成熟的中文分词插件。INFINI Easysearch 内置并深度优化了 IK 分词器，使其在处理超大规模词库时内存占用更低，加载速度更快。 … - [Generic 线程池核心大小配置](https://easysearch.cn/knowledge-base/easysearch_config/thread_pool.generic.core/): 配置项作用 # thread_pool.generic.core 配置项用于控制通用线程池的核心线程数。 Generic 线程池用于处理各种通用任务，包括内部系统操作和管理任务。 配置项属性 # 配置路径: thread_pool.generic.core 数据类型: Integer（整数） 默认值: 4 是否可选: 是 作用域: NodeScope（节点级别） 动态更新: 是（可以动态更 … - [Management 线程池核心大小配置](https://easysearch.cn/knowledge-base/easysearch_config/thread_pool.management.core/): 配置项作用 # thread_pool.management.core 配置项用于控制管理线程池的核心线程数。 Management 线程池用于处理集群管理操作，如节点状态监控、集群元数据操作等。 配置项属性 # 配置路径: thread_pool.management.core 数据类型: Integer（整数） 默认值: 1 是否可选: 是 作用域: NodeScope（节点级别） 动态 … - [NAME unknown token token - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/name-unknown-token-token-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # [NAME] unknown token [token] 表示查询解析器在一开始就没有读到它期望的字段名，而是读到了错误的 token 类型，因此整个查询对象的起始结构就不合法。 从页面中的源码可见，这里对应 TermsSetQueryBuilder.fromXContent(...)。它要求在进入查询对象后， … - [Sampler 聚合无法应用于字段 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/sampler-aggregation-cannot-be-applied-to-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.7 1. 错误异常的基本描述 # Sampler 聚合无法应用于字段 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [start array expected [snapshots] - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/start-array-expected-snapshots-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.9 1. 错误异常的基本描述 # start array expected [snapshots] 出现在解析快照仓库元数据时。源码明确要求 snapshots 字段当前 token 必须是 START_ARRAY，如果拿到的是对象、字符串或其他结构，就会抛出这条异常。 常见现象 # 列快照、读取仓库 metadata 或恢复仓库状态时失败。 … - [Type - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/type-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Type 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返回 400、404、409、429、500 … - [使用试用许可证时必须显式启用安全功能 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/security-must-be-explicitly-enabled-when-using-a-trial-license-how-to-solve-this-elasticsearch-exception/): 适用版本： 7-7 1. 错误异常的基本描述 # 使用试用许可证时必须显式启用安全功能 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [准备发布时发生意外错误](https://easysearch.cn/knowledge-base/elasticsearch_error/unexpected-error-while-preparing-to-publish-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.17 1. 错误异常的基本描述 # 准备发布时发生意外错误 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [分析线程池队列大小配置](https://easysearch.cn/knowledge-base/easysearch_config/thread_pool.analyze.queue_size/): 配置项作用 # thread_pool.analyze.queue_size 配置项用于控制分析线程池的队列大小。 当所有分析线程都在忙碌时，新的分析请求会被放入队列等待。队列大小决定了系统能够缓冲多少待处理的分析请求。 配置项属性 # 配置路径: thread_pool.analyze.queue_size 数据类型: Integer（整数） 默认值: 256 是否可选: 是 作用域: … - [刷新索引](https://easysearch.cn/knowledge-base/easysearch_api/refresh-index/): 刷新索引，使自上次刷新以来执行的所有操作对搜索可见。 API # POST /_refresh GET /_refresh POST /{index}/_refresh GET /{index}/_refresh API 的作用 # 该 API 用于刷新索引，使最近索引的文档对搜索可见。这是 Easysearch 近实时搜索功能的核心机制。 刷新的作用 # 将内存中的文档写入新的段 使新文 … - [国产搜索引擎选型指南：Easysearch vs 腾讯云 Elasticsearch Service](https://easysearch.cn/knowledge-base/basic/easysearch-vs-tencent-elasticsearch-service-selection-guide/): 在数据驱动与智能化时代，搜索引擎已经不仅仅用于简单的关键词查找，而被广泛用于日志分析、实时大数据检索、智能问答、推荐系统、知识图谱等核心业务中。随着国产技术的快速发展，自主可控的国产搜索引擎方案逐渐成为企业级选型中的重要方向。 本文以 Easysearch 与 腾讯云 Elasticsearch Service 作为对比对象，从多维度分析它们的能力差异与适用场景，帮助企业做出更清晰的技术选型判断。 … - [地理坐标必须是数字——如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/geo-coordinates-must-be-numbers-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 地理坐标必须是数字— 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [字段属性值 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/property-value-on-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.1-7.15 1. 错误异常的基本描述 # 字段属性值 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [字段类型应为 percolator - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/expected-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # expected field [field] to be of type [percolator]; but is of type [type] 表示 Elasticsearch 在执行 percolate 查询时，找到了对应的字段，但该字段的实际类型与 percolator 类型不匹配，因此抛出异常。 注意：这不是字段不存在的报错（ … - [并行度应至少为 1 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/parallelism-should-be-at-least-1-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.4-7.17 1. 错误异常的基本描述 # 并行度应至少为 1 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [必须使用小写 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/must-be-lowercase-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 必须使用小写 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [找不到指定名称的 OpenID Connect Realm - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-find-openid-connect-realm-with-name-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.2-8.9 1. 错误异常的基本描述 # Cannot find OpenID Connect realm with name [realm_name] 表示 Elasticsearch 安全模块在处理 OpenID Connect（OIDC）认证请求时，无法根据请求中指定的 realm 名称找到对应的已配置 realm，因此认证流程无法继续。 OpenID Connect … - [无效精度 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/invalid-precision-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 无效精度 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返回 400、404、409、429、500 … - [无法删除数据帧 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-delete-data-frame-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.2-7.4 1. 错误异常的基本描述 # 无法删除数据帧 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返回 400、404、409、429、500 … - [无法解析指定监视器状态，期望字段是对象（Could not parse watch status for [watchId]. expecting field to be an object）- 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-watch-status-for-expecting-field-to-be-an-object-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.x 1. 错误异常的基本描述 # could not parse watch status for [watchId]. expecting field [...] to be an object; found [...] instead 与不带 for [watchId] 的版本语义相同，只是日志里额外指出了出错的具体 watch ID。 这对定位问题很有帮助，因为你 … - [无法解析监视器条件，期望空对象却发现其他内容（Could not parse condition for watch. expected an empty object but found）- 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-condition-for-watch-expected-an-empty-object-but-found-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.x 1. 错误异常的基本描述 # could not parse [...] condition for watch [...]. expected an empty object but found [...] 表示某类 Watcher 条件要求值必须是一个空对象，但解析器在对象开始处或对象内部读到了不允许的内容。 从保留代码看，这类错误典型出现在 always / … - [无法解析监视器条件，期望空对象却发现其他内容（Unable to parse condition for watch. expected an empty object but found）- 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unable-to-parse-condition-for-watch-expected-an-empty-object-but-found-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.x 1. 错误异常的基本描述 # unable to parse [...] condition for watch [...]. expected an empty object but found [...] 与 could not parse ... expected an empty object but found ... 的含义基本一致，都是在说明：当前条件 … - [未知的日期时间单位 ID - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unknown-date-time-unit-id-id-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Unknown date time unit id [id] 表示 Elasticsearch 在将内部日期时间单位编号（id）映射回对应的枚举值时，读到了一个不在预定义列表中的未知编号，从而抛出 ElasticsearchException。 该异常属于内部序列化/反序列化异常，通常不直接由用户 DSL 语法错误触发，而是出现在节点间 … - [未知的标记 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unknown-token-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.4-7.15 1. 错误异常的基本描述 # 未知的标记 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返回 400、404、409、429、500 … - [状态在计算新的CS更新时被更改 – 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/state-was-mutated-while-calculating-new-cs-update-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.17 1. 错误异常的基本描述 # 状态在计算新的CS更新时被更改 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [请求断路器类型配置](https://easysearch.cn/knowledge-base/easysearch_config/indices.breaker.request.type/): 配置项作用 # indices.breaker.request.type 配置项控制请求断路器的实现类型。 默认值 # memory 配置类型 # 动态配置 配置格式 # # 默认配置 indices.breaker.request.type: memory - [迁移过程中发生多个错误 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/multiple-errors-occurred-during-migration-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.11-8.9 1. 错误异常的基本描述 # 迁移过程中发生多个错误 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [进程 ID 文件配置](https://easysearch.cn/knowledge-base/easysearch_config/pidfile/): 配置项概述 # pidfile 配置项指定节点进程 ID（PID）文件的存储路径，用于进程管理和监控。 配置项 默认值 说明 pidfile “"（空） PID 文件路径 配置说明 # pidfile # 配置项作用：指定节点进程 ID 文件的存储位置。PID 文件包含运行中节点的进程 ID，便于进程管理工具定位和控制节点进程。 默认 … - [远程传输异常 (remote_transport_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/remote_transport_exception/): 为什么这个错误发生 # remote_transport_exception 表示远程节点在执行操作时抛出异常。这是一个包装异常，包含远程节点的实际错误信息。 这个错误可能由以下原因引起： 远程节点故障：远程节点正在执行操作时崩溃或失败 超时：远程节点执行操作时间过长导致超时 资源不足：远程节点内存或 CPU 不足 操作冲突：远程节点上存在冲突的操作 数据问题：远程节点上的数据有问题导致操作失 … - [遇到更高term - encountered term > used outdated getTask term – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/higher-term-encountered-encountered-term-used-outdated-gettask-term-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # 遇到更高term - encountered term > used outdated getTask term 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还 … - [集群信息更新配置](https://easysearch.cn/knowledge-base/easysearch_config/cluster.info.update/): 配置项概述 # cluster.info.update.* 配置项组用于控制主节点收集和更新集群信息（如磁盘使用率、分片大小）的行为。这些信息用于分片分配决策和磁盘阈值管理。 配置项 默认值 说明 cluster.info.update.interval 30s 集群信息更新间隔 cluster.info.update.timeout 15s … - [a sample must have at least one join key found none - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/a-sample-must-have-at-least-one-join-key-found-none-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.6-8.9 1. 错误异常的基本描述 # a sample must have at least one join key; found none 是 Elasticsearch 在使用 sampler aggregation（采样聚合）或相关的查询功能时抛出的配置错误。当你在构造 sampler 类型的聚合时，如果没有正确配置必要的 join key（连接键），或者采样配置中 … - [a search request cannot be profiled if document level security - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/a-search-request-cannot-be-profiled-if-document-level-security-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # a search request cannot be profiled if document level security 是 Elasticsearch 在尝试对搜索请求进行性能分析（profile）时抛出的安全限制错误。当你使用 _search?profile=true API 对搜索请求进行性能分析，但目标索引或集群启用了** … - [Easysearch 同义词搜索功能实现详解](https://easysearch.cn/knowledge-base/usage/easysearch-synonym-search-implementation/): 在搜索引擎的实际应用中，用户输入的关键词往往与数据库中存储的文本存在差异。例如： 用户搜 “手机”，但商品名称写的是 “智能电话” 或 “iPhone”。 用户搜 “士多啤梨”，但库存里叫 “草莓”。 用户搜 “AWS”，但文章里写的是 “亚马逊云科技”。 如果没有同义词处理，这些相关的文档将无法被检索到（召回率低）。本文将详细介绍如何在 INFINI Easysearch 中配置和优化同义词 … - [GeoJSON类型用于地理点只能是Point - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/geojson-type-for-geo-point-can-only-be-point-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.2-8.2 1. 错误异常的基本描述 # GeoJSON类型用于地理点只能是Point 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Key必须使用一致的协议http或https - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/key-must-use-a-consistent-scheme-http-or-https-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.5-8.9 1. 错误异常的基本描述 # Key必须使用一致的协议http或https 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [rescore TopHits 执行失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/rescore-tophits-failed-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 在 TopHits 场景下执行重排时，如果底层 rescorer 抛出异常，Elasticsearch 会包装成： Rescore TopHits Failed 它往往不是最终根因，而是对内部 IOException 的再次封装。 2. 为什么会发生这个错误 # 从源码看， … - [Rollup 统计刷新间隔配置](https://easysearch.cn/knowledge-base/easysearch_config/monitor.rollup.stats_refresh_interval/): 配置项作用 # monitor.rollup.stats_refresh_interval 配置项用于控制Rollup 任务统计信息的定期刷新间隔时间。 此配置决定了系统多久从 .easysearch-ilm-config 索引中获取和缓存一次滚动任务统计信息，包括处理的页面数、文档数、索引时间等指标。 配置项属性 # 配置路径: … - [不支持 null_value 属性 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/property-null-value-is-not-supported-for-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.9 1. 错误异常的基本描述 # 不支持 null_value 属性 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [不支持的形状类型 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unsuppoted-shape-type-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.2-7.9 1. 错误异常的基本描述 # 不支持的形状类型 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [主分片缺失操作异常 (primary_missing_action_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/primary_missing_action_exception/): 为什么这个错误发生 # primary_missing_action_exception 表示在执行操作时找不到主分片。这通常发生在尝试对分片执行写入或更新操作时，主分片不可用或不存在。 这个错误可能由以下原因引起： 主分片未分配：主分片未被分配到任何节点 主分片正在迁移：主分片正在迁移到另一个节点 主分片故障：主分片所在的节点发生故障 分片恢复中：主分片正在恢复过程中 节点离线：承载主分片的 … - [从事务日志恢复失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-recover-from-translog-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 从事务日志恢复失败 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [分片不再重新定位 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/shard-is-no-longer-relocating-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.16-8.9 1. 错误异常的基本描述 # 分片不再重新定位 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [分片恢复状态同步重试延迟配置](https://easysearch.cn/knowledge-base/easysearch_config/indices.recovery.retry_delay_state_sync/): 配置项作用 # indices.recovery.retry_delay_state_sync 配置项控制因集群状态同步问题导致分片恢复失败后的重试延迟时间。这些问题包括本地节点尚未在远程节点注册、远程分片尚未启动等状态同步问题。 配置项类型 # 该配置项为动态配置，可以在运行时通过集群设置 API 进行修改。 默认值 # 500ms 是否必需 # 可选配置项（有默认值） 取值范围 # … - [向量检索 vs 全文检索：Easysearch 如何理解意思而非字面](https://easysearch.cn/knowledge-base/basic/vector-search-vs-full-text-search-how-easysearch-understands-meaning/): 当你在电商网站搜索“便宜好用的电脑”，但商品标题里写的却是“高性价比笔记本”，你希望搜索引擎能足够“聪明”，为你返回正确的结果。然而，传统的搜索引擎很可能会因为找不到“便宜”或“电脑”这两个字，而无情地告诉你“未找到相关商品”。 这就是搜索领域长期存在的“语义鸿沟”——用户表达的“意思”和数据库里存储的“字面”无法匹配。 为了跨越这道鸿沟，搜索技术经历了一场深刻的进化。Easysearch 作为现 … - [字段 fieldName 不支持的查询关系 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/query-relation-not-supported-for-field-fieldname-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.16-8.9 1. 错误异常的基本描述 # 字段 fieldName 不支持的查询关系 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [字段参数不支持该字段类型——如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/field-parameter-is-not-supported-for-field-type-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 字段参数不支持该字段类型— 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [字段类型不支持超过3维——如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/field-type-does-not-accept-3-dimensions-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 字段类型不支持超过3维— 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [所有分片失败 – 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/all-shards-failed-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # all shards failed 是 Elasticsearch 搜索阶段的汇总性异常，表示这次查询命中的所有目标分片都没有成功返回结果。它通常不是最原始的错误，而是协调节点在汇总各分片执行结果时给出的最终结论。真正的根因往往藏在 failed_shards 里的具体异常里，例如字段类型不支持、聚合执行失败、脚本报错、分片不可用、索引 … - [执行集群状态更新失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-execute-cluster-state-update-source-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # 执行集群状态更新失败 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [提交异步搜索](https://easysearch.cn/knowledge-base/easysearch_api/submit-async-search/): 在指定索引上提交异步搜索请求，允许执行长时间运行的复杂查询而不阻塞客户端。 API # POST /{index}/_async_search API 的作用 # 该 API 用于在指定索引上提交异步搜索请求。异步搜索可以： 长时间运行而不阻塞客户端 使用返回的任务 ID 来检查搜索状态和获取结果 避免客户端长时间等待复杂查询的完成 限制 # 不支持滚动（scroll）查询 不支持仅建 … - [搜索因SearchPhaseExecutionException失败，将使用新的scroll重试 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/search-failed-due-to-searchphaseexecutionexception-will-attempt-again-with-new-scroll-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.8-8.9 1. 错误异常的基本描述 # 搜索因SearchPhaseExecutionException失败，将使用新的scroll重试 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索 … - [无法打开到空节点的连接 – 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/can-t-open-connection-to-a-null-node-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 无法打开到空节点的连接 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法标准化点 - 不是数字 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-normalize-the-point-not-a-number-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 无法标准化点 - 不是数字 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法获取 leader 集群上 leaderIndex 索引的主分片统计信息 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-get-shard-stats-for-primary-of-index-leaderindex-on-leader-cluster-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.1-8.9 1. 错误异常的基本描述 # 无法获取 leader 集群上 leaderIndex 索引的主分片统计信息 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 … - [无法解析监视器的 Action：ID 包含空白字符 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-action-for-watch-id-contains-whitespace-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # Watcher 的 actions 段本质上是一个 JSON 对象，键名就是 action id。Elasticsearch 在遍历这些键名时，会先校验 id 是否合法；如果 id 中包含空格、制表符或其他空白字符，就会直接拒绝解析。 典型报错如下： could not parse action [send email] for … - [未知的排序方向 dir - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unknown-order-direction-dir-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.16-8.9 1. 错误异常的基本描述 # 未知的排序方向 dir 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [查询悬空索引](https://easysearch.cn/knowledge-base/easysearch_api/get-dangling-index/): 查询集群中所有悬空索引（Dangling Indices）的列表。 API 格式 # GET /_dangling API 作用 # 该 API 用于查询集群中所有悬空索引。悬空索引是指在磁盘上存在但未在集群状态中注册的索引。这种情况通常发生在： 索引已从集群状态中删除，但数据文件仍存在于磁盘上 集群元数据丢失，但索引文件仍然保留 索引被手动从磁盘删除，但集群状态仍然引用它 API … - [网络绑定地址配置](https://easysearch.cn/knowledge-base/easysearch_config/network.host/): 配置项作用 # network.host 配置项指定 Easysearch 绑定的网络地址，决定节点监听哪些网络接口。此配置影响节点是否能被其他节点和客户端访问。 配置项类型 # 该配置项为静态配置，需要在启动时设置，修改后需要重启节点才能生效。 默认值 # 未配置（使用 _local_，即回环地址） 是否必需 # 生产环境必需（开发环境可选） 配置值说明 # … - [节点级限流处理动作配置](https://easysearch.cn/knowledge-base/easysearch_config/cluster.throttle.node.write.action/): 配置项作用 # 当节点级限流触发时的处理动作。 默认值 # DROP 取值范围 # DROP：丢弃超出的请求 THROTTLE：延迟处理 配置格式 # # 丢弃超出的请求（默认） cluster.throttle.node.write.action: DROP # 延迟处理 cluster.throttle.node.write.action: THROTTLE - [连接并发关闭 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/connection-concurrently-closed-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.4 1. 错误异常的基本描述 # 连接并发关闭 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返回 400、404、409、429、500 … - [通配符查询分析配置](https://easysearch.cn/knowledge-base/easysearch_config/indices.query.query_string.analyze_wildcard/): 配置项作用 # indices.query.query_string.analyze_wildcard 配置项用于控制在通配符和前缀查询中是否对词项进行分词器分析。 当启用时，通配符词项会被分词器分解成多个词元（tokens），从而实现更灵活的匹配模式。 配置项属性 # 配置路径: indices.query.query_string.analyze_wildcard 数据类型: … - [a sample requires a minimum of 2 queries found - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/a-sample-requires-a-minimum-of-2-queries-found-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.6-8.9 1. 错误异常的基本描述 # a sample requires a minimum of 2 queries; found [1] 是 Elasticsearch 的 Rank Evaluation API（排名评估 API）抛出的参数验证错误。当你使用 Rank Evaluation API 来评估查询排名质量时，必须在请求中提供至少 2 个查询（原始查询和测试 … - [cannot descend into the dek blob container - 无法进入 DEK Blob 容器如何解决](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-descend-into-the-dek-blob-container-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.12-8.6 1. 错误异常的基本描述 # Cannot descend into the DEK blob container 表示 Elasticsearch 在访问快照仓库（Snapshot Repository）时，检测到当前路径试图直接进入用于数据加密密钥（Data Encryption Key，DEK）的内部 blob 容器，因此主动拒绝访问。这是一个明确的保护机 … - [Easysearch Hot vs Cold 数据分层策略详解](https://easysearch.cn/knowledge-base/usage/easysearch-hot-vs-cold-data-tiering-strategy/): 一、概述 # 在日志存储、指标监控等时序数据场景中，数据访问频率随时间推移而显著降低。Easysearch 提供了 Hot 和 Cold 两层数据分层策略，实现热数据高性能存储与冷数据低成本归档的平衡。 二、Hot 与 Cold 对比 # 维度 Hot 阶段 Cold 阶段 数据特征 最新写入，频繁查询 历史归档，极少查询 存储介质 NVMe SSD / 高性能 SSD … - [Easysearch vs Elasticsearch：核心差异一文讲清](https://easysearch.cn/knowledge-base/basic/easysearch-vs-elasticsearch-core-differences/): 引言：同源不同路，差异在“本土化”与“合规性” # Easysearch 与 Elasticsearch（简称 ES）师出同门——Easysearch 衍生自 ES 7.10.2 版本（ES 最后一个 Apache 2.0 开源协议版本），但后续发展路径完全不同。ES 转向 SSPL/ELv2 协议，侧重全功能生态；Easysearch 坚守 “本土化适配+合规优先”，聚焦国内企业核心需求。两者 … - [include/exclude子句中的数组元素应为字符串值 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/array-elements-in-include-exclude-clauses-should-be-string-values-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # array elements in include/exclude clauses should be string values（include/exclude 子句中的数组元素应为字符串值）是 Elasticsearch 在解析查询 DSL 时抛出的 illegal_argument_exception 类型异常。该错误明确表示： … - [Meta值只能是字符串但得到其他类型 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/meta-values-can-only-be-strings-but-got-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.6-7.15 1. 错误异常的基本描述 # Meta值只能是字符串但得到其他类型 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [More like this 查询要求 fields 不能为空——如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/more-like-this-requires-fields-to-be-non-empty-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # More like this 查询要求 fields 不能为空— 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Policy 不能为空 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/policy-must-not-be-null-how-to-solve-this-elasticsearch-exception/): 适用版本： 7-8.9 1. 错误异常的基本描述 # Policy 不能为空 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Rollup搜索期间未找到实时索引或汇总索引 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/no-indices-live-or-rollup-found-during-rollup-search-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.2-8.9 1. 错误异常的基本描述 # Rollup搜索期间未找到实时索引或汇总索引 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [不是有效的正则表达式文件 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/not-a-valid-regular-expression-file-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 不是有效的正则表达式文件 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [不能包含空格 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/must-not-contain-whitespace-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 这里的 must not contain whitespace 指的是快照名称 snapshotName 中含有空格，因而被 InvalidSnapshotNameException 拒绝。源码里这条规则紧跟在“不能为空”之后：只要 snapshotName.contains(" ") 为真，请求就不会进入真正的快照 … - [事务日志操作修剪失败 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-trim-translog-operations-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 事务日志操作修剪失败 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [写线程池配置](https://easysearch.cn/knowledge-base/easysearch_config/thread_pool.write/): 配置项作用 # thread_pool.write 配置项控制用于执行索引、更新、批量写入等写操作的线程池。写线程池处理所有对数据节点的单文档写入操作，包括索引、更新、删除等操作。 配置项类型 # 该配置项为静态配置，需要在启动时设置，修改后需要重启节点才能生效。 默认值 # size: CPU 核心数（allocatedProcessors） queue_size: 10000 … - [创建安全角色](https://easysearch.cn/knowledge-base/easysearch_api/create-security-role/): 注意：POST /_security/role API 在 Easysearch 中未实现。请使用 PUT /_security/role/{name} API 来创建角色。 API 说明 # POST /_security/role 端点在 Easysearch 中未实现。调用此端点将返回 501 Not Implemented 错误。 替代方法 # 要创建安全角色，请使用 PUT … - [刷新失败 (flush_failed_engine_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/flush_failed_engine_exception/): 为什么这个错误发生 # flush_failed_engine_exception 表示将内存数据刷新到磁盘时失败。 如何修复 # 1. 检查磁盘空间 # GET /_cat/allocation?v df -h 2. 检查磁盘错误 # dmesg | grep -i error 3. 重启分片 # POST /_cluster/reroute?retry_failed=true 4. … - [刷新索引到磁盘](https://easysearch.cn/knowledge-base/easysearch_api/flush-index/): 将索引的内存数据刷新到磁盘存储，清空事务日志，确保数据持久化。 API # POST /_flush GET /_flush POST /{index}/_flush GET /{index}/_flush API 的作用 # 该 API 用于执行索引的 Flush 操作，将内存中的数据持久化到磁盘。 Flush 的作用 # 将内存中的段写入磁盘 清空内部事务日志（translog） 释放 … - [布尔查询子句数量限制配置](https://easysearch.cn/knowledge-base/easysearch_config/indices.query.bool.max_clause_count/): 配置项作用 # indices.query.bool.max_clause_count 配置项限制布尔查询（bool query）中允许的最大子句数量。此配置直接影响 Lucene 层面的查询复杂度控制，防止过于复杂的查询导致性能问题或内存溢出。 配置项类型 # 该配置项为动态配置，可以在运行时通过集群设置 API 进行修改。 默认值 # 1024 是否必需 # 可选配置项（有默认值） 取 … - [引用字段必须映射为 geo_point 类型 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/referenced-field-must-be-mapped-to-geo-point-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.1 1. 错误异常的基本描述 # 引用字段必须映射为 geo_point 类型 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无效模板——如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/invalid-template-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 无效模板— 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无效的元素类型 o，可用类型为 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/invalid-element-type-o-available-types-are-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.6-8.9 1. 错误异常的基本描述 # 无效的元素类型 o，可用类型为 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法列出网关内容 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-list-content-of-gateway-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.3 1. 错误异常的基本描述 # Failed to list content of gateway 出现在分片快照删除或清理旧网关内容时。源码会先执行 blobContainer.listBlobs() 读取当前网关/仓库目录中的 blob 列表，再根据结果重建分片级快照清单；如果列举 blob 这一步抛出 IOException， … - [无法将配置值解析为百分比或字节 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unable-to-parse-as-either-percentage-or-bytes-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.13-8.x 1. 错误异常的基本描述 # unable to parse [{}={}] as either percentage or bytes 表示 Elasticsearch 在解析某个配置项时，发现其值既不是合法的百分比格式，也不是合法的字节大小格式。该异常通常在节点启动、动态更新集群设置（cluster settings API） … - [无法确定数据类型 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-determine-datatype-for-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 无法确定数据类型 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [没有可用分片——如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/no-shard-available-for-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-6.8 1. 错误异常的基本描述 # 没有可用分片— 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返回 400、404、409、429、500 … - [添加项目失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-add-items-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.4-8.9 1. 错误异常的基本描述 # 添加项目失败 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [用户无权访问服务 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/user-is-not-permitted-to-access-service-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.7-7.15 1. 错误异常的基本描述 # 用户无权访问服务 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [索引不存在返回空响应 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/index-does-not-exist-returning-empty-response-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.9-8.9 1. 错误异常的基本描述 # 索引不存在返回空响应 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [索引名称未设置 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/index-name-was-not-set-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 索引名称未设置 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [索引请求缓存启用配置](https://easysearch.cn/knowledge-base/easysearch_config/config_index.requests.cache.enable/): 配置项作用 # index.requests.cache.enable 配置项控制索引级别请求缓存的启用状态。 默认值 # true 配置类型 # 索引级配置 配置格式 # # 默认配置：启用 index.requests.cache.enable: true # 禁用请求缓存 index.requests.cache.enable: false - [组件模板匹配请求名称未找到 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/component-template-matching-request-name-not-found-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # 组件模板匹配请求名称未找到 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [缺少名称导出器的导出器类型 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/missing-exporter-type-for-name-exporter-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 缺少名称导出器的导出器类型 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [聚合桶数量限制配置](https://easysearch.cn/knowledge-base/easysearch_config/search.max_buckets/): 配置项作用 # search.max_buckets 配置项限制单个搜索/聚合请求中可以创建的桶（bucket）的最大数量。此配置用于防止聚合操作生成过多桶导致内存溢出或性能问题。 配置项类型 # 该配置项为动态配置，可以在运行时通过集群设置 API 进行修改。 默认值 # 65535 是否必需 # 可选配置项（有默认值） 取值范围 # 0 ~ Integer.MAX_VALUE 工作原 … - [集群只读允许删除块配置](https://easysearch.cn/knowledge-base/easysearch_config/cluster.blocks.read_only_allow_delete/): 配置项作用 # cluster.blocks.read_only_allow_delete 配置项控制集群的"只读但允许删除"状态。与 cluster.blocks.read_only 不同，此配置在禁止写入操作的同时，允许删除操作。这通常用于磁盘空间不足场景，允许用户删除数据以释放空间。 配置项类型 # 该配置项为动态配置，可以在运行时通过集群设置 API 进行修改。 默 … - [预期字段为数组 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/expected-array-for-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.9 1. 错误异常的基本描述 # 预期字段为数组 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Easysearch 批量操作：使用 Bulk API 高效写入](https://easysearch.cn/knowledge-base/usage/easysearch-bulk-api-efficient-data-writing/): 在 Easysearch 的世界里，如果你还在使用单条 PUT 或 POST 请求来循环写入数据，那么你的系统性能可能正遭受着严重的浪费。 想象一下搬家场景：是每次手里拿一个箱子跑一趟（单条 API），还是把所有箱子装进大卡车一次性拉走（Bulk API）？答案显而易见。 Bulk API 是 Easysearch 提供的高效批量操作接口。经过测试，合理使用 Bulk API … - [Easysearch 核心架构解读：集群、节点、索引与分片](https://easysearch.cn/knowledge-base/basic/easysearch-core-architecture-cluster-node-index-and-shard/): 一、分布式架构：集群与节点的协同基石 # Easysearch 本质是分布式搜索引擎，其架构核心在于通过集群（Cluster）与节点（Node）的协同，实现数据的分布式存储与并行计算。 集群（Cluster） 定义：由一个或多个节点组成的逻辑集合，通过唯一集群名标识，协同完成数据索引、搜索及管理任务。 核心特性：支持单节点轻量化部署（适用于开发测试），也可扩展至数百台服务器的大规模集群（满足 … - [HTTP 初始行最大长度配置](https://easysearch.cn/knowledge-base/easysearch_config/http.max_initial_line_length/): 配置项作用 # http.max_initial_line_length 配置项指定 HTTP 初始行（请求行或状态行）的最大长度。这包括方法、URI 和 HTTP 版本（请求）或状态码和原因短语（响应）。 默认值 # 4KB 配置类型 # 静态配置 取值范围 # 支持字节单位（如 4KB, 8KB） 配置格式 # # 默认配置 http.max_initial_line_length: … - [NAME join field – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/name-join-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # NAME join field 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [TCP 无延迟配置](https://easysearch.cn/knowledge-base/easysearch_config/network.tcp.no_delay/): 配置项作用 # network.tcp.no_delay 配置项控制是否启用 TCP 的 TCP_NODELAY 选项。启用后，将禁用 Nagle 算法，允许小数据包立即发送，而不是等待累积成更大的数据包。这可以降低延迟，但可能增加网络开销。 配置项类型 # 该配置项为静态配置，需要在启动时设置，修改后需要重启节点才能生效。 默认值 # true（启用无延迟模式） 是否必需 # 可选配置 … - [传输序列化异常 (transport_serialization_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/transport_serialization_exception/): 为什么这个错误发生 # transport_serialization_exception 表示传输层在序列化或反序列化数据时失败。传输层使用序列化来在网络间传递请求和响应数据。 这个错误可能由以下原因引起： 版本不兼容：节点间的版本不一致，序列化格式不兼容 类定义变更：类的定义在不同版本间发生变化 数据损坏：传输的数据在序列化或网络传输过程中损坏 类加载失败：目标节点无法加载某个类 自定义类 … - [在集群状态中找不到脚本 ID —— 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unable-to-find-script-id-in-cluster-state-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 在集群状态中找不到脚本 ID — 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [字段不支持 - 必须是以下之一 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/field-not-supported-must-be-one-of-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.3-8.9 1. 错误异常的基本描述 # 字段不支持 - 必须是以下之一 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [字段名 multiFieldName 是 name 的多字段，不能包含点号 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/field-name-multifieldname-which-is-a-multi-field-of-name-cannot-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # 字段名 multiFieldName 是 name 的多字段，不能包含点号 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常 … - [当分片处于备份状态时尝试恢复 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/trying-to-recover-when-the-shard-is-in-backup-state-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 当分片处于备份状态时尝试恢复 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [恢复被取消——如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/recovery-was-cancelled-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.8-8.9 1. 错误异常的基本描述 # 恢复被取消— 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返回 400、404、409、429、500 … - [恢复重试失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-retry-recovery-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 恢复重试失败 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [找不到插件类 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-find-plugin-class-classname-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Could not find plugin class [className] 是 Elasticsearch 在插件加载阶段抛出的异常，表示节点启动时无法通过类加载器（ClassLoader）找到并加载指定的插件主类。该异常通常发生在节点启动初期，会导致目标插件加载失败，严重时可能造成节点无法正常加入集群或服务启动中断。 常见现象 # … - [搜索命中的 _source 解析失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/hit-failed-to-parse-source-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.x 1. 错误异常的基本描述 # [hit] failed to parse [_source] 出现在 Elasticsearch 解析搜索结果命中时。也就是说，搜索已经命中了文档，但在把命中的 _source 读回并转换成内部表示时失败了。 这通常意味着 索引里存储的 _source 字节内容本身就有问题，而不是查询语法有问题。 常见现象 # 某个索引或个别文档 … - [故障检测Ping间隔配置](https://easysearch.cn/knowledge-base/easysearch_config/discovery.zen.fd.ping_interval/): 配置项作用 # discovery.zen.fd.ping_interval 配置项用于控制故障检测机制中ping 请求的发送间隔时间。 节点会按照此间隔定期向主节点或其他节点发送 ping 请求，以检测它们是否仍然存活。 配置项属性 # 配置路径: discovery.zen.fd.ping_interval 数据类型: TimeValue（时间值） 默认值: 1s（1秒） 是否可选: … - [文档未找到 index id – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/document-not-found-index-id-how-to-solve-this-elasticsearch-exception/): 适用版本： 8-8.9 1. 错误异常的基本描述 # 文档未找到 index id 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法为规则 ruleType 值创建 IP 过滤器 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unable-to-create-ip-filter-for-rule-ruletype-value-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # 无法为规则 ruleType 值创建 IP 过滤器 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法启动 Data Frame 任务，分配说明显示失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-start-dataframe-allocation-explanation-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.2-7.4 1. 错误异常的基本描述 # 这个异常说明 dataframe 持久化任务已经脱离初始分配阶段，但仍然没有被成功分配到任何节点，因此 Elasticsearch 认为启动失败。 2. 为什么会发生这个错误 # 源码逻辑： if (assignment != null && assignment.equals(INITIAL_ASSIGNMENT) … - [无法找到指定名称的客户端 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unable-to-find-client-with-name-clientname-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 无法找到指定名称的客户端 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法解析电子邮件：存在空字段 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-email-empty-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 这个异常表示 Watcher 在解析邮件正文对象时，读到一个值，但当前并没有对应的字段名。它与 unexpected field 不同，unexpected field 是字段名存在但不被识别；这里则是字段名本身缺失或对象结构已经损坏。 2. 为什么会发生这个错误 # 源码中的核心分支如下： if (token == … - [无法解析监视器的 Actions：期望对象却得到了其他类型 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-actions-for-watch-expected-an-object-but-found-instead-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # 在 Watcher 中，actions 必须是一个 JSON 对象，内部每个字段名对应一个 action id，每个字段值对应一个具体 action 定义。若 Elasticsearch 在解析 actions 时没有拿到 START_OBJECT，就会直接抛出当前异常。 典型报错： could not parse actions … - [更新监控迁移设置失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-update-monitoring-migration-settings-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.11-8.9 1. 错误异常的基本描述 # 更新监控迁移设置失败 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [最小主节点数量配置](https://easysearch.cn/knowledge-base/easysearch_config/discovery.zen.minimum_master_nodes/): 配置项作用 # discovery.zen.minimum_master_nodes 配置项用于定义主节点选举所需的最小主节点资格节点数量。 这是防止集群脑裂（split-brain）的关键配置，确保只有当有足够数量的主节点资格节点参与时，才能形成有效的主节点选举。 配置项属性 # 配置路径: discovery.zen.minimum_master_nodes 数据类型: integer … - [查询快照状态](https://easysearch.cn/knowledge-base/easysearch_api/get-snapshot-status/): 此 API 用于获取快照的当前状态信息。 API # GET /_snapshot/_status GET /_snapshot/{repository}/_status GET /_snapshot/{repository}/{snapshot}/_status API 的作用 # 返回快照的当前状态信息，包括： 正在进行中的快照：正在执行的快照进度 已完成的快照：快照的详细统计信息 快照 … - [查询规则库详情](https://easysearch.cn/knowledge-base/easysearch_api/get-ruleset-detail/): 获取指定规则库（规则仓库）的详细信息和配置。 API 格式 # GET .match_rules/_doc/{repo_id} API 作用 # 该 API 用于检索指定规则库的完整信息，包括： 规则库名称和描述 规则内容（表达式列表） 版本和状态信息 编译信息和编译节点 数值字段声明和复合索引定义 API 参数 # 路径参数 # … - [格式错误的内容必须以对象开头——如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/malformed-content-must-start-with-an-object-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 格式错误的内容必须以对象开头— 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [测试查询响应出现意外状态 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unexpected-status-from-response-of-test-query-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.4-7.6 1. 错误异常的基本描述 # 测试查询响应出现意外状态 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [系统索引不能作为 searchable snapshot 挂载 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/system-index-cannot-be-mounted-as-searchable-snapshots-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.10-8.9 1. 错误异常的基本描述 # 这里的 system index [{}] cannot be mounted as searchable snapshots 不是网络问题，也不是仓库不可达，而是 Elasticsearch 在执行挂载请求前做的一条明确产品规则校验。源码先取出 mountedIndexName， … - [缺少必需的 Email to 字段 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/missing-required-email-to-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # missing required email [to] field 是 Elasticsearch Watcher 在发送邮件通知时抛出的配置类异常。该错误表示 Watcher 在执行 email action 时，经过 account defaults 合并后，邮件对象的 to 字段仍然为空，导致无法构造合法的邮件消息，发送流程在真正 … - [节点领导者健康检查失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/node-leader-failed-health-checks-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.9-7.15 1. 错误异常的基本描述 # 节点领导者健康检查失败 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [解析 Jira Project 失败：期望对象却得到了其他类型 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-jira-project-expected-an-object-but-found-instead-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # Watcher 的 Jira action 中，project 节点必须是一个对象，用来承载项目键、字段映射等信息。如果解析器在 project 位置没有看到 START_OBJECT，就会抛出当前异常。 典型报错： failed to parse jira project. expected an object, but found … - [解析搜索请求失败：source 必须是对象 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-search-source-source-must-be-an-object-but-found-instead-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # failed to parse search source. source must be an object; but found [{}] instead 表示 Elasticsearch 已经开始读取请求体，但拿到的第一个 token 不是 START_OBJECT。换句话说，请求体本该是一个 JSON 对象，例如 { … - [请求版本时无法禁用存储字段 – 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/stored-fields-cannot-be-disabled-if-version-is-requested-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.9 1. 错误异常的基本描述 # 请求版本时无法禁用存储字段 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [资源重载低频检查间隔配置](https://easysearch.cn/knowledge-base/easysearch_config/resource.reload.interval.low/): 配置项作用 # resource.reload.interval.low 配置项控制低频资源检查的轮询间隔。 默认值 # 如配置名所示 配置类型 # 静态配置 配置格式 # # 默认配置 resource.reload.interval.low: default - [过滤器解析问题 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/problems-parsing-filter-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 过滤器解析问题 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [a snapshot is already running - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/a-snapshot-is-already-running-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.17 1. 错误异常的基本描述 # a snapshot is already running 是 Elasticsearch 在创建快照时抛出的并发控制异常。当你尝试在某个快照仓库（repository）上创建新快照，但该仓库已经有正在执行的快照任务时，就会触发此错误。Elasticsearch 的快照机制采用串行执行策略，同一仓库同一时间只能有一个活跃的快照任务。 … - [authentication token does not have openid connect metadata - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/authentication-token-does-not-have-openid-connect-metadata-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.2-8.9 1. 错误异常的基本描述 # authentication token does not have openid connect metadata 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日 … - [Easysearch 的推荐方案 text / keyword 怎么选？](https://easysearch.cn/knowledge-base/usage/easysearch-text-vs-keyword-choosing-field-types/): 在设计 Easysearch 的索引 Mapping 时，开发者面临的第一个也是最高频的灵魂拷问就是： “这个字段，我到底该设为 text 还是 keyword？” 选错了会有什么后果？ 选了 text：无法排序，无法聚合，或者聚合报错 Fielddata is disabled。 选了 keyword：搜“手机”搜不到“苹果手机”，大小写必须完全一致。 本文将深入剖析这两种类型的底层区别，并 … - [ISM 操作验证启用配置](https://easysearch.cn/knowledge-base/easysearch_config/index_state_management.action_validation.enabled/): 配置项作用 # index_state_management.action_validation.enabled 配置项用于控制在执行索引状态管理（ISM）操作之前是否进行验证。 启用验证可以在执行诸如 rollover、delete、force_merge 等危险操作前先检查条件，防止误操作导致数据丢失或服务中断。 配置项属性 # 配置路径: … - [Max shingle size 必须至少为 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/max-shingle-size-must-be-at-least-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # Max shingle size 必须至少为 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [NAME getPreferredName query must - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/name-getpreferredname-query-must-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.15-7.15 1. 错误异常的基本描述 # NAME getPreferredName query must 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 … - [NAME父字段未配置父类型——如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/name-parent-field-has-no-parent-type-configured-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-6.8 1. 错误异常的基本描述 # NAME父字段未配置父类型— 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [request body is required - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/request-body-is-required-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # request body is required 是一个非常前置的请求校验异常。源码中的 requiredContent() 会先判断当前请求是否真的带了 body，只要没有，就立刻抛出 ElasticsearchParseException，不会继续后面的业务解析。 常见现象 # … - [不能以下划线开头 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/must-not-start-with-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 不能以下划线开头 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [副本复制重试超时配置](https://easysearch.cn/knowledge-base/easysearch_config/indices.replication.retry_timeout/): 配置项作用 # indices.replication.retry_timeout 配置项控制副本复制操作失败后重试的总超时时间。当向副本节点执行操作（如索引、删除、更新等）失败时，系统会在指定时间内进行重试，超过此时间后将停止重试并返回错误。 配置项类型 # 该配置项为动态配置，可以在运行时通过索引设置 API 进行修改。 默认值 # 60s 是否必需 # 可选配置项（有默认值） 取值范 … - [命令缺少to_node参数 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/command-missing-the-to-node-parameter-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 命令缺少to_node参数 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [国产化适配全景：Easysearch 对国产芯片、操作系统支持情况一览](https://easysearch.cn/knowledge-base/insight/easysearch-domestic-adaptation-overview-chip-os-compatibility/): 面对国产化替代的浪潮，企业在技术选型时最关心的问题之一往往是：“这款产品真的能在我们现有的国产化环境里顺畅运行吗？” 尤其是对于企业级搜索引擎这类核心基础软件，其与底层芯片、操作系统的适配深度，直接决定了整个系统的性能、稳定性与安全性。 Easysearch 从设计之初就将 “深度国产化适配” 视为核心目标，致力于构建一张覆盖主流技术路线的全景式兼容网络。 1 、适配全景图：全面覆盖主流生态 # … - [字段解析错误 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/error-parsing-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # 字段解析错误 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [客户端传输节点嗅探配置](https://easysearch.cn/knowledge-base/easysearch_config/client.transport.sniff/): 配置项作用 # client.transport.sniff 配置项用于控制 TransportClient 是否启用节点嗅探（sniff）功能。 节点嗅探允许 TransportClient 自动发现集群中的所有数据节点，并建立到这些节点的连接，而不仅仅是连接到手动配置的节点。 配置项属性 # 配置路径: client.transport.sniff 数据类型: boolean 默认值: … - [文档计数](https://easysearch.cn/knowledge-base/easysearch_api/document-count/): 获取匹配查询条件的文档数量，不返回实际的文档内容。 API # GET /_count POST /_count GET /{index}/_count POST /{index}/_count API 的作用 # 该 API 用于获取匹配查询条件的文档数量。 Count API vs Search API # API 返回内容 性能 /_count … - [无法发送消息，事件循环正在关闭 – 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-send-message-event-loop-is-shutting-down-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.8 1. 错误异常的基本描述 # 无法发送消息，事件循环正在关闭 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法启动 Data Frame Analytics - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-start-data-frame-analytics-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.5-7.10 1. 错误异常的基本描述 # Cannot start data frame analytics [job_id] because it has already been started 是一个 409 CONFLICT 状态异常，表示尝试启动一个已经处于运行状态的 Data Frame Analytics 任务。这个错误不是数据损坏或节点故障，而是任务状态冲突。 … - [无法执行正则表达式查询时 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/regexp-queries-cannot-be-executed-when-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.7-7.15 1. 错误异常的基本描述 # 无法执行正则表达式查询时 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法解析节点ID - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-resolve-node-ids-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.6-8.11 1. 错误异常的基本描述 # 无法解析节点ID 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [时间序列索引仅支持合成源 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/time-series-indices-only-support-synthetic-source-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.9-8.9 1. 错误异常的基本描述 # 时间序列索引仅支持合成源 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [期望多点对象时未提供数据 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/no-data-provided-for-multipoint-object-when-expecting-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # 期望多点对象时未提供数据 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [未知的形状操作 parser text - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unknown-shape-operation-parser-text-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 未知的形状操作 parser text 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [查询字符串引用分析器 quoteAnalyzer 未找到 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/query-string-quote-analyzer-quoteanalyzer-not-found-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 查询字符串引用分析器 quoteAnalyzer 未找到 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口 … - [查询所有摄入管道](https://easysearch.cn/knowledge-base/easysearch_api/get-all-ingest-pipelines/): 获取集群中所有摄入管道的配置信息。 API 格式 # GET /_ingest/pipeline API 作用 # 该 API 用于检索集群中所有摄入管道： 返回所有可用的管道配置 查看管道描述和处理器列表 支持获取所有管道的概览信息 API 参数 # 查询参数 # 参数 类型 是否必填 默认值 描述 master_timeout Time 否 默认超时 连接主节点的超时 … - [模板必须设置映射 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/template-must-have-mapping-set-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.1 1. 错误异常的基本描述 # 模板必须设置映射 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [源节点已取消恢复 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/source-has-canceled-the-recovery-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.16-8.9 1. 错误异常的基本描述 # 源节点已取消恢复 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [由于 SearchPhaseExecutionException 重新初始化滚动 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/reinitializing-scroll-due-to-searchphaseexecutionexception-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.7 1. 错误异常的基本描述 # 由于 SearchPhaseExecutionException 重新初始化滚动 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 … - [监听器线程池配置](https://easysearch.cn/knowledge-base/easysearch_config/thread_pool.listener/): 配置项作用 # thread_pool.listener 相关配置项控制用于执行事件监听器回调的线程池。监听器线程池用于处理各种集群和索引事件的监听器通知。该配置项已弃用（Deprecated）。 配置项类型 # 该配置项为静态配置，需要在启动时设置，修改后需要重启节点才能生效。 默认值 # thread_pool.listener.size: half_processors_max_10 … - [索引名称时间格式设置 getKey 无效的索引名称时间格式 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/index-name-time-format-setting-getkey-invalid-index-name-time-format-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.5 1. 错误异常的基本描述 # 索引名称时间格式设置 getKey 无效的索引名称时间格式 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接 … - [聚合名称不支持正则表达式风格的include/exclude – 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/aggregation-name-cannot-support-regular-expression-style-include-exclude-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.7 1. 错误异常的基本描述 # Aggregation [name] cannot support regular expression style include/exclude settings as they can only be applied to string fields 是 Elasticsearch 在执行聚合查询时抛出的异常。该错误的核心含义是： … - [获取分片锁失败 (shard_lock_obtain_failed_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/shard_lock_obtain_failed_exception/): 为什么这个错误发生 # shard_lock_obtain_failed_exception 表示无法获取分片的内存锁。 如何修复 # 1. 检查分片状态 # GET /_cat/shards?v 2. 重试操作 # 等待锁释放后重试。 3. 重启分片 # POST /_cluster/reroute?retry_failed=true 预防措施 # 避免长时间操作 监控分片状态 - [融合还是专业？深度剖析 ParadeDB 与 Easysearch 的架构哲学](https://easysearch.cn/knowledge-base/basic/paradedb-easysearch-architecture-philosophy-comparison/): 在构建现代数据应用时，“PostgreSQL + Elasticsearch”是一个绕不开的经典架构。我们依赖 PostgreSQL 处理核心的事务性业务，同时将数据同步到 Elasticsearch 中，以获得强大的全文搜索和分析能力。这个模式行之有效，但也带来了无尽的痛苦：数据同步的延迟与不一致、ETL 管道的脆弱性、双倍的运维成本、跨系统查询的复杂性…… 面对这些困境，技术社区分裂出两种截然 … - [解析存储库失败缺少存储库类型 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-repository-missing-repository-type-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # failed to parse repository [...] missing repository type 表示 Elasticsearch 在解析仓库定义时，发现该 repository metadata 缺少 type 字段。由于仓库类型决定了底层实现是 fs、s3、gcs、azure 还是其他类型，没有 type 就无法创建 … - [路由值必须是字符串但发现了其他类型 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/routing-values-must-be-strings-but-found-how-to-solve-this-elasticsearch-exception/): 适用版本： 8-8 1. 错误异常的基本描述 # 路由值必须是字符串但发现了其他类型 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [这不是 HTTP 端口 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/this-is-not-an-http-port-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 这不是 HTTP 端口 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [集群初始主节点配置](https://easysearch.cn/knowledge-base/easysearch_config/cluster.initial_master_nodes/): 配置项作用 # cluster.initial_master_nodes 配置项指定在集群首次初始化时的候选主节点列表。此配置仅在集群第一次启动时使用，用于确定集群的投票配置（Voting Configuration），防止脑裂。 配置项类型 # 该配置项为静态配置，需要在启动时设置。仅在集群首次初始化时生效。 默认值 # 空列表（需要手动配置） 是否必需 # 首次启动必需（多节点集群） … - [could not parse time - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-time-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # could not parse time [value] 是 Elasticsearch 在解析时间值或时间配置时抛出的异常。此错误表示时间值、时间单位、时区或日期字段格式不满足解析器要求。 该错误通常在解析请求体时就会返回 ElasticsearchParseException，常见于 daily、weekly、monthly … - [could not parse time value time value cannot be negative - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-time-value-time-value-cannot-be-negative-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # could not parse time value [value]. Time value cannot be negative. 是 Elasticsearch 在解析 TimeValue（时间值）时抛出的异常。此错误表示时间值文本本身已经成功转成 TimeValue，但结果是负数，不被当前路径接受。 该错误发生在时间值解析成功后， … - [could not parse transform for watch expected an array of transform objects - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-transform-for-watch-expected-an-array-of-transform-objects-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # could not parse [TYPE] transform for watch [watchId]. expected an array of transform objects; but found [token] instead 是 Elasticsearch Watcher 在解析 chain transform（链式转换） … - [NonReserved 只能包含 token 但发现嵌套规则 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/nonreserved-can-only-contain-tokens-found-nested-rule-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # NonReserved 只能包含 token 但发现嵌套规则 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口 … - [Positions increment gap 必须为正数但得到负数 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/positions-increment-gap-must-be-positive-got-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.9 1. 错误异常的基本描述 # Positions increment gap 必须为正数但得到负数 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 … - [truncated date math - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/truncated-date-math-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # truncated date math [expr] 是 Elasticsearch 在解析日期数学表达式（date math）时抛出的异常。当 date math 表达式读到一半时字符串已经结束，后续内容不完整，就会触发此错误。例如写了 now-、now+1 但没写单位，或者请求在传输过程中被截断。 常见现象 # … - [Unknown key for a - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unknown-key-for-a-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # unknown key for a 表示 Elasticsearch 在解析 Ingest Processor 配置中的数组字段时，遇到了无法识别的元素类型。 从源码可见，这个异常在 Ingest Processor 的数组解析路径中抛出，当数组元素类型与预期不符时触发。 典型报错 # ParsingException: … - [Voting only node skipping local publication to - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/voting-only-node-skipping-local-publication-to-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.2-8.9 1. 错误异常的基本描述 # Voting only node skipping local publication to 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起 … - [Write 线程池大小配置](https://easysearch.cn/knowledge-base/easysearch_config/thread_pool.write.size/): 配置项作用 # thread_pool.write.size 配置项用于控制写入线程池的线程数量。 这是处理索引、更新、删除等写操作的核心线程池。 配置项属性 # 配置路径: thread_pool.write.size 数据类型: Integer（整数） 默认值: CPU核心数 是否可选: 是 作用域: NodeScope（节点级别） 动态更新: 是（可以动态更新，无需重启） … - [传输绑定异常 (bind_transport_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/bind_transport_exception/): 为什么这个错误发生 # bind_transport_exception 表示无法绑定到传输端口（9300）。 如何修复 # 1. 检查端口占用 # netstat -tuln | grep 9300 2. 修改传输端口 # # easysearch.yml transport.port: 9301 3. 停止冲突进程 # kill <pid> 预防措施 # … - [使用 search_after 时 from 必须为 0 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/from-parameter-must-be-set-to-0-when-search-after-is-used-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 当请求同时设置了 search_after 和 from > 0，Elasticsearch 会报错： `from` parameter must be set to 0 when `search_after` is used. 2. 为什么会发生这个错误 # search_after 本身就是一种翻页游标机制，它通过上一页最后 … - [共享数据目录配置](https://easysearch.cn/knowledge-base/easysearch_config/path.shared_data/): 配置项作用 # path.shared_data 配置项用于指定使用自定义数据路径的索引的共享存储根目录。 当索引使用 index.data_path 设置自定义数据路径时，该路径必须是 path.shared_data 的子路径。这允许将特定索引存储在不同的物理位置，实现数据隔离和灵活存储管理。 配置项属性 # 配置路径: path.shared_data 数据类型: String（目录路 … - [响应通道channel request getHttpChannel已关闭 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/response-channel-channel-request-gethttpchannel-closed-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.14-8.9 1. 错误异常的基本描述 # 响应通道channel request getHttpChannel已关闭 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 … - [国产搜索引擎选型指南：Easysearch vs 阿里云 OpenSearch](https://easysearch.cn/knowledge-base/basic/easysearch-vs-aliyun-opensearch-selection-guide/): 随着企业级应用对搜索功能的多样需求不断增长，如何选择合适的搜索引擎方案已成为关键决策之一。本文围绕两款国产主流搜索引擎 Easysearch 和 阿里云 OpenSearch 进行对比分析，帮助你从不同维度理解它们的定位、能力和适用场景，从而做出更理性的选型决策。 一、国产搜索引擎的现状 # 搜索是大多数信息系统的重要组成部分。从网站搜索、文档检索到日志分析，再到智能问答和推荐系统，搜索引擎承 … - [容忍来自其他主节点的Ping次数配置](https://easysearch.cn/knowledge-base/easysearch_config/discovery.zen.max_pings_from_another_master/): 配置项作用 # discovery.zen.max_pings_from_another_master 配置项用于控制当前主节点在触发重新加入集群前，可以容忍来自其他主节点的 ping 次数。 当集群中出现多个主节点（脑裂场景）时，此配置决定本地主节点在检测到冲突后可以容忍多少次来自其他主节点的 ping。 配置项属性 # 配置路径: … - [找不到名称字段的字段映射 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/no-field-mapping-can-be-found-for-the-field-with-name-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 找不到名称字段的字段映射 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [挂载快照响应未完成 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/mount-snapshot-response-failed-to-complete-got-response-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.10-8.9 1. 错误异常的基本描述 # 这条错误来自 mount searchable snapshot 请求返回后的状态检查。源码中只有当响应状态是 OK 或 ACCEPTED 时才认为挂载流程正常继续；如果拿到的是其他状态，就会记录 mount snapshot response failed to complete， … - [无效的Unicode字符代码——如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/invalid-unicode-character-code-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.13-8.9 1. 错误异常的基本描述 # 无效的Unicode字符代码— 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法创建 Blob Store - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-create-blob-store-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 这条 cannot create blob store 出现在仓库启动阶段。源码会先调用具体仓库实现的 createBlobStore()；如果底层已经抛出 RepositoryException，就原样上抛，否则会被统一包装成 RepositoryException(metadata.name(), "cannot … - [无法将证书写入ZIP文件 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-write-certificate-to-zip-file-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.6-8.9 1. 错误异常的基本描述 # 无法将证书写入ZIP文件 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法解析字段，期望字符串数组但发现其他值 (expected a string array but found value instead) - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-field-expected-a-string-array-but-found-value-instead-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # 无法解析字段，期望字符串数组但发现其他值 (expected a string array but found value instead) 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只 … - [无法验证签名身份信息 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-verify-signed-authentication-information-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 无法验证签名身份信息 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [查询字段数据缓存](https://easysearch.cn/knowledge-base/easysearch_api/get-field-data-cache/): 此 API 用于显示集群中每个数据节点的字段数据（fielddata）当前使用的堆内存大小。 API # GET /_cat/fielddata GET /_cat/fielddata/{fields} API 的作用 # 返回集群中每个节点上按字段分组的 fielddata 内存使用情况统计。Fielddata 是 Lucene 在排序和聚合操作时使用的缓存数据，常驻堆内存。 此 API 用 … - [查询脚本语言](https://easysearch.cn/knowledge-base/easysearch_api/get-script-language/): 此 API 用于获取 Easysearch 集群中支持的脚本语言信息。 API # GET /_script_language API 的作用 # 返回集群支持的脚本语言信息，包括： types_allowed：集群允许的脚本类型（如 inline、stored） language_contexts：每种脚本语言支持的使用上下文（如 score、update、aggs 等） 此 API 帮 … - [每节点总分片数限制配置](https://easysearch.cn/knowledge-base/easysearch_config/cluster.routing.allocation.total_shards_per_node/): 配置项作用 # cluster.routing.allocation.total_shards_per_node 配置项控制每个节点上允许分配的最大分片总数（包括主分片和副本分片）。当节点的分片数量达到此限制时，新的分片将不会被分配到该节点。 配置项类型 # 该配置项为动态配置，可以在运行时通过集群设置 API 进行修改。 默认值 # -1（无限制） 是否必需 # 可选配置项（有默认值） … - [类型只能是 Point – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/type-for-can-only-be-point-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.3-8.9 1. 错误异常的基本描述 # 类型只能是 Point 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [自动建字段在 Easysearch 中该不该开？](https://easysearch.cn/knowledge-base/usage/easysearch-dynamic-mapping-best-practices/): 在 Easysearch 的索引构建过程中，有一个非常方便但也容易被误用的机制——动态建字段（Dynamic Mapping）。这意味着当你把一个文档写入索引时，系统可能会自动根据字段内容推断出字段类型并自动添加字段定义。对于初学者来说，这种“自适应”行为看起来很友好，但它在真实生产环境中也可能带来风险。 本文将从原理、风险、示例和实践建议四个层面讲清楚问题： 👉 自动建字段到底该不该开？怎么开？ … - [获取集群状态超时 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/timed-out-getting-cluster-state-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.11-8.9 1. 错误异常的基本描述 # 获取集群状态超时 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [解析 dynamic attachments 时 template 字段失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-dynamic-attachments-failed-to-parse-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # could not parse dynamic attachments. failed to parse [template] field 表示 Elasticsearch 已经识别到 dynamic attachments 配置中的 template 字段， … - [认证令牌必须存在用于领域验证 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/authentication-token-must-present-for-realms-authentication-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.16-8.9 1. 错误异常的基本描述 # 认证令牌必须存在用于领域验证 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [跨集群复制跟随者操作批处理大小配置](https://easysearch.cn/knowledge-base/easysearch_config/plugins.replication.follower.index.ops_batch_size/): 配置项作用 # plugins.replication.follower.index.ops_batch_size 配置项用于控制跟随者索引处理的操作批处理大小。 配置项属性 # 配置路径: plugins.replication.follower.index.ops_batch_size 数据类型: Integer（整数） 默认值: 50000 是否可选: 是 作用域: … - [零样本分类结果没有数据](https://easysearch.cn/knowledge-base/elasticsearch_error/zero-shot-classification-result-has-no-data-how-to-solve-this-elasticsearch-exception/): 适用版本： 8-8.9 1. 错误异常的基本描述 # 零样本分类结果没有数据 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [access restricted by workflow - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/access-restricted-by-workflow-how-to-solve-this-elasticsearch-exception/): 适用版本： Elasticsearch 8.9+（引入了 workflow 语义的 RBAC 权限模型） 1. 错误异常的基本描述 # access restricted by workflow 是 Elasticsearch 在 RBAC（基于角色的访问控制） 鉴权阶段抛出的权限拒绝异常。当分配给用户的角色中配置了 workflows 字段（工作流限制），而当前请求的操作类型不在允许的工作流 … - [Easysearch 数据重建与迁移：使用 Reindex API 零停机升级索引](https://easysearch.cn/knowledge-base/usage/easysearch-reindex-api-zero-downtime-migration/): 在企业级搜索应用中，随着业务的发展，数据模型（Mapping）往往需要迭代更新。然而，Easysearch（以及 Elasticsearch）底层的倒排索引一旦生成，其字段类型和分词方式便不可直接修改。面对“修改字段类型”、“调整分片数量”或“开启数据压缩”等需求时，数据重建（Reindex） 是必经之路。 如何在 TB 级海量数据重建过程中，保证业务不中断、查询不抖动？ … - [Expected COMMA or – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/expected-comma-or-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # Expected COMMA or 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Geo context必须是对象或字符串——如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/geo-context-must-be-an-object-or-string-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Geo context必须是对象或字符串— 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Get 线程池队列大小配置](https://easysearch.cn/knowledge-base/easysearch_config/thread_pool.get.queue_size/): 配置项作用 # thread_pool.get.queue_size 配置项用于控制文档获取线程池的队列大小。 当所有获取线程都在忙碌时，新的获取请求会被放入队列等待。 配置项属性 # 配置路径: thread_pool.get.queue_size 数据类型: Integer（整数） 默认值: 1000 是否可选: 是 作用域: NodeScope（节点级别） 动态更新: 是（可以动态更 … - [watch 的 input 缺少类型字段 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-input-for-watch-expected-field-indicating-the-input-type-but-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.x 1. 错误异常的基本描述 # could not parse input for watch [id]. expected field indicating the input type; but found an empty object instead 表示 Elasticsearch Watcher 在解析 watch 定义时，成功进入了 input 对象，但 … - [Windows 控制台事件处理器](https://easysearch.cn/knowledge-base/easysearch_config/bootstrap.ctrlhandler/): 配置项作用 # bootstrap.ctrlhandler 配置项控制是否在 Windows 系统上注册控制台事件处理器（Console Ctrl Handler）。该处理器可以捕获 Windows 的控制台关闭事件，实现优雅关闭。 配置项类型 # 该配置项为静态配置，需要在启动时设置，修改后需要重启节点才能生效。 默认值 # true（启用） 是否必需 # 可选配置项 工作原理 # 当 … - [为导出器设置了未知的导出器类型 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unknown-exporter-type-type-set-for-exporter-name-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 为导出器设置了未知的导出器类型 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [倒排索引：让 Easysearch 实现“秒搜”的核心黑科技](https://easysearch.cn/knowledge-base/basic/inverted-index-core-technology-for-instant-search/): 在处理 PB 级海量数据时，为什么传统数据库（如 MySQL）使用 LIKE 模糊查询会慢如蜗牛，而 INFINI Easysearch 却能瞬间返回结果？ 这并非魔法，而是源于底层数据结构设计的根本差异。传统数据库是为了“记录”而生，而 Easysearch 是为了“检索”而生。这种差异的核心，就是我们今天要解密的黑科技——倒排索引（Inverted Index）。 … - [关闭索引](https://easysearch.cn/knowledge-base/easysearch_api/close-index/): 关闭一个或多个索引，使其不再响应读写请求，但保留磁盘数据。 API # POST /{index}/_close POST /_close API 的作用 # 该 API 用于关闭索引。关闭的索引： 不再响应读写请求 不占用内存资源 保留磁盘数据 可以通过 _open API 重新打开 使用场景 # … - [出现意外的空推理响应 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unexpected-empty-inference-response-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.6-8.9 1. 错误异常的基本描述 # 出现意外的空推理响应 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [分片恢复网络重试延迟配置](https://easysearch.cn/knowledge-base/easysearch_config/indices.recovery.retry_delay_network/): 配置项作用 # indices.recovery.retry_delay_network 配置项控制因网络相关问题导致分片恢复失败后的重试延迟时间。网络问题包括连接超时、网络中断、传输层故障等。 配置项类型 # 该配置项为动态配置，可以在运行时通过集群设置 API 进行修改。 默认值 # 5s 是否必需 # 可选配置项（有默认值） 取值范围 # 0 ~ 正无穷 配置格式 # # 默认配 … - [刷新汇总索引 rollupIndexName 失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-refresh-rollup-index-rollupindexname-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.3-8.9 1. 错误异常的基本描述 # 刷新汇总索引 rollupIndexName 失败 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [刷新线程池配置](https://easysearch.cn/knowledge-base/easysearch_config/thread_pool.refresh/): 配置项作用 # thread_pool.refresh 相关配置项控制用于执行索引刷新（Refresh）操作的线程池。索引刷新操作将内存中的文档写入新段，使文档对搜索可见。该线程池采用伸缩线程池类型。 配置项类型 # 该配置项为静态配置，需要在启动时设置，修改后需要重启节点才能生效。 默认值 # thread_pool.refresh.core: 1 … - [同名快照已在进行中——如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/snapshot-with-the-same-name-is-already-in-progress-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.1-8.9 1. 错误异常的基本描述 # snapshot with the same name is already in-progress 表示你试图创建的快照名称，已经被同一仓库中一个活跃的快照任务占用。根据源码，Elasticsearch 会先遍历 runningSnapshots.forRepo(repositoryName)，只要发现有正在执行的快照名称与本次请求相 … - [对象映射尝试解析字段时出错 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/object-mapping-for-mapper-name-tried-to-parse-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # 对象映射尝试解析字段时出错 表示某个字段在 mapping 中被定义为 object 或 nested，但实际写入的文档却给了字符串、数字、布尔值等具体值。源码片段里的原始报错就是：Elasticsearch 试图按对象解析字段，却只拿到了一个“具体值”。 常见现象 # 文档写入、批量导入或 reindex 时直接返回 400。 … - [强制删除数据流不受支持，因为数据流任务正在运行——如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/force-delete-datafeed-is-not-supported-because-the-datafeed-task-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-6.8 1. 错误异常的基本描述 # 强制删除数据流不受支持，因为数据流任务正在运行— 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [意外的响应类型配置错误 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unexpected-response-type-while-is-configured-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # 意外的响应类型配置错误 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [数据流匹配请求名称未找到 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/data-stream-matching-request-name-not-found-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.9-8.11 1. 错误异常的基本描述 # 数据流匹配请求名称未找到 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [数据流请求名称已存在 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/data-stream-request-name-already-exists-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.9-8.11 1. 错误异常的基本描述 # 数据流请求名称已存在 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [文件系统监控刷新间隔配置](https://easysearch.cn/knowledge-base/easysearch_config/monitor.fs.refresh_interval/): 配置项作用 # monitor.fs.refresh_interval 配置项用于控制文件系统信息（FsInfo）监控数据的缓存刷新间隔。 此配置决定了 FsService 多久刷新一次文件系统信息，包括磁盘使用情况、IO 统计等数据。通过缓存机制减少频繁的文件系统查询。 配置项属性 # 配置路径: monitor.fs.refresh_interval 数据类型: TimeValue（时间 … - [无法修改字段名称的index设置 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/setting-index-cannot-be-modified-for-field-name-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.9 1. 错误异常的基本描述 # 无法修改字段名称的index设置 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法分析字段 fieldName 的值 fieldValue - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-analyze-value-fieldvalue-of-field-fieldname-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 无法分析字段 fieldName 的值 fieldValue 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法删除不存在的任务 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-remove-task-with-id-taskid-the-task-no-longer-exists-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 无法删除不存在的任务 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法在接收前一个值之前开始发布下一个值 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-start-publishing-next-value-before-accepting-previous-one-how-to-solve-this-elasticsearch-exception/): 适用版本： 7-8.9 1. 错误异常的基本描述 # 无法在接收前一个值之前开始发布下一个值 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法更新ID为taskId的任务，该任务已不存在 – 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-update-task-with-id-taskid-the-task-no-longer-exists-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 无法更新ID为taskId的任务，该任务已不存在 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法解析监视器条件，缺少必需的条件类型字段（Could not parse condition for watch. missing required condition type field）- 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-condition-for-watch-missing-required-condition-type-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.x 1. 错误异常的基本描述 # could not parse condition for watch [<watch_id>]. missing required condition type field 是 Elasticsearch Watcher 功能在解析监视器（watch）定义时抛出的解析异常。该错误表示 Watcher … - [映射解析异常 (mapper_parsing_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/mapper_parsing_exception/): 为什么这个错误发生 # mapper_parsing_exception 表示索引映射定义解析失败。 如何修复 # 1. 检查映射语法 # # 使用验证 API GET /<index>/_mapping 2. 修复字段类型 # 确保字段类型与数据匹配。 3. 删除并重新创建映射 # # 删除索引 DELETE /<index> # 使用正确的映射创建 PUT … - [查询任务（Cat格式）](https://easysearch.cn/knowledge-base/easysearch_api/get-tasks-cat-format/): 以紧凑的表格形式返回当前正在运行的任务信息。 API 格式 # GET /_cat/tasks API 作用 # 该 API 以表格形式返回当前正在运行的任务： 显示所有节点的运行任务 显示任务 ID、动作、类型等信息 显示任务开始时间和运行时长 显示任务所在的节点信息 API 参数 # 查询参数 # 参数 类型 是否必填 默认值 描述 format String 否 文 … - [模式集无效——如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/the-set-of-patterns-is-invalid-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.7-8.9 1. 错误异常的基本描述 # 模式集无效— 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [等待完成超时 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/timed-out-waiting-for-completion-of-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.6 1. 错误异常的基本描述 # 等待完成超时 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [结果处理器意外终止 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unexpected-death-of-the-result-processor-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 结果处理器意外终止 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [缺失事件仅支持序列类型——如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/missing-events-are-supported-only-for-sequences-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.9-8.9 1. 错误异常的基本描述 # 缺失事件仅支持序列类型— 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [a character not a string required for escaping found - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/a-character-not-a-string-required-for-escaping-found-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # a character not a string required for escaping found 是 Elasticsearch 在解析查询 DSL 时抛出的异常。当查询中使用了转义字符（escape character）语法，但提供的转义字符不是单个字符而是字符串时，就会触发此错误。这通常发生在使用通配符查询（wildcard … - [Easysearch 全文搜索：match 与 multi_match 查询](https://easysearch.cn/knowledge-base/basic/easysearch-full-text-search-match-and-multi-match/): 如果说精确查询（Term Query）是数据库的基础能力，那么**全文搜索（Full Text Search）**才是 INFINI Easysearch 作为搜索引擎的灵魂所在。 与 SQL 中的 LIKE %keyword% 不同，Easysearch 的全文搜索不仅性能更优，还能理解语言的结构。它不只是简单的字符匹配，而是基于倒排索引和分词分析的智能检索。本文将带你掌握最核心的两个查 … - [Easysearch 节点角色，配错比不配更危险](https://easysearch.cn/knowledge-base/usage/easysearch-node-roles-configuration-matters/): 在开发或测试环境中，我们习惯了“开箱即用”——启动一个 Easysearch 节点，它既存数据，又管集群，还要处理请求。但在生产环境中，这种“全能型”节点往往是灾难的源头。本文将深入解析 Master、Data、Ingest 三大核心角色的职责边界，揭示为什么错误的节点规划比不配置更危险，并给出不同规模集群的架构建议。 Easysearch 的一个节点（Node）默认是“全能”的。如果你不修改 … - [HTTP Netty 工作线程数配置](https://easysearch.cn/knowledge-base/easysearch_config/http.netty.worker_count/): 配置项作用 # http.netty.worker_count 配置项指定 HTTP 处理的工作线程数量。设置为 0 表示根据可用处理器数量自动检测。 默认值 # 0（自动检测） 配置类型 # 静态配置 取值范围 # 0 或正整数 配置格式 # # 默认配置：自动检测 http.netty.worker_count: 0 # … - [Unknown key in the template - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unknown-key-in-the-template-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # unknown key in the template 是 Elasticsearch 在解析索引模板（Index Template）配置时抛出的 ElasticsearchParseException 异常。当 Elasticsearch 读取模板定义时，会在固定的键名列表中进行匹配，如果发现无法识别的键名，就会抛出此异常，并拒绝该模 … - [Watch reporting Error response when trying to trigger reporting generation - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/watch-reporting-error-response-when-trying-to-trigger-reporting-generation-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # Watch reporting Error response when trying to trigger reporting generation 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因 … - [watch 的时间字段解析失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-watch-failed-to-parse-time-value-for-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # could not parse watch [id]. failed to parse time value for field [field] 表示 Elasticsearch Watcher 在解析某个 watch 定义中的时间字段时失败。该错误属于解析阶段异常，意味着 watch 的 JSON 结构本身可以被读取，但其中某个时间 … - [Wrapper Query 格式错误，期望 query 字段却读到了别的字段 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/wrapper-query-malformed-expected-query-but-was-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误说明 # [wrapper] query malformed; expected 'query' but was <field_name> 是 Elasticsearch 在解析 wrapper 查询时抛出的 ParsingException。该错误表示 wrapper 对象的 JSON 结构中，解析器期望读取到名为 query 的字段，但实际 … - [仅在索引未关闭时允许操作 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/operation-only-allowed-when-not-closed-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 仅在索引未关闭时允许操作 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [写入悬空索引信息配置](https://easysearch.cn/knowledge-base/easysearch_config/gateway.write_dangling_indices_info/): 配置项作用 # gateway.write_dangling_indices_info 配置项用于控制节点是否将悬空索引信息写入磁盘。 悬空索引信息是索引元数据的持久化记录，用于帮助节点识别那些存在于磁盘上但不在当前集群元数据中的索引。 配置项属性 # 配置路径: gateway.write_dangling_indices_info 数据类型: boolean 默认值: true 是否可 … - [删除快照](https://easysearch.cn/knowledge-base/easysearch_api/delete-snapshot/): 从快照仓库中删除一个或多个快照。 API 格式 # DELETE /_snapshot/{repository}/{snapshot} API 作用 # 该 API 用于从快照仓库中删除快照： 删除快照并清理所有关联文件 保留与其他快照共享的文件 支持同时删除多个快照 API 参数 # 路径参数 # 参数 类型 是否必填 默认值 描述 {repository} … - [字段无效的年月值，期望字符串、数值或数组 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/invalid-year-month-value-for-field-expected-string-number-value-or-an-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # 字段无效的年月值，期望字符串、数值或数组 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [安全异常 (security_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/security_exception/): 为什么这个错误发生 # security_exception 是与安全和权限相关的通用异常。这个错误表示当前用户或客户端没有执行请求操作的权限，或者安全验证失败。 这个错误可能由以下原因引起： 认证失败：提供的用户名或密码不正确 权限不足：用户没有执行特定操作的权限 Token 过期：访问令牌（JWT、Bearer Token 等）已过期 TLS/SSL 问题：SSL 证书验证失败或配置错误 … - [已注册的ACS URL为[{}]但认证请求包含[{}]——如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/the-registered-acs-url-for-this-service-provider-is-but-the-authentication-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.7-7.15 1. 错误异常的基本描述 # 已注册的ACS URL为[{}]但认证请求包含[{}]— 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可 … - [无效的动态名称表达式缺少闭合括号 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/invalid-dynamic-name-expression-missing-closing-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # 无效的动态名称表达式缺少闭合括号 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法删除内部索引 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-delete-internal-indices-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.16-8.9 1. 错误异常的基本描述 # 无法删除内部索引 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法更新临时汇总索引 tmpIndexName 的设置 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unable-to-update-settings-of-temp-rollup-index-tmpindexname-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.12-8.2 1. 错误异常的基本描述 # 无法更新临时汇总索引 tmpIndexName 的设置 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返 … - [无法更新索引映射中路径类型的属性 – 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/can-t-update-attribute-for-type-path-in-index-mapping-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.7 1. 错误异常的基本描述 # 无法更新索引映射中路径类型的属性 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法解析 Watch，遇到意外 token - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-watch-unexpected-token-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.x 1. 错误异常的基本描述 # could not parse watch [<id>]; unexpected token [<token>] 表示解析器在期望读取字段名的位置，实际遇到了不应该出现的 token。 根据日志上下文，这个异常发生在 currentFieldName == null 的分支，也就是解析器还没有读到合法字段名时，就 … - [无法解析监视器条件，比较运算字段期望是对象（Could not parse condition for watch. expected an object for field [op]）- 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-condition-for-watch-expected-an-object-how-to-solve-this-elasticsearch-exception/): 1. 错误异常的基本描述 # could not parse [...] condition for watch [...]. expected an object for field [...] but found [...] instead 是 Elasticsearch Watcher 功能中一个常见的 DSL 解析错误。该错误表示在解析 Watcher 的 condition 条件时，解 … - [无法重新分配ID为taskId的任务，该任务已不存在 – 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-reassign-task-with-id-taskid-the-task-no-longer-exists-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 无法重新分配ID为taskId的任务，该任务已不存在 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能 … - [无法验证辅助用户身份 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-authenticate-secondary-user-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.7-8.9 1. 错误异常的基本描述 # 无法验证辅助用户身份 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [最终归约失败——如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/final-reduction-failed-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.4-8.9 1. 错误异常的基本描述 # 最终归约失败— 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [滚动搜索](https://easysearch.cn/knowledge-base/easysearch_api/scroll-search/): 使用滚动上下文从单个搜索请求中检索大量结果，保持搜索一致性视图。 API # 获取滚动结果 # GET /_search/scroll POST /_search/scroll GET /_search/scroll/{scroll_id} POST /_search/scroll/{scroll_id} 清除滚动上下文 # DELETE /_search/scroll DELETE … - [索引恢复类型配置](https://easysearch.cn/knowledge-base/easysearch_config/config_index.recovery.type/): 配置项作用 # index.recovery.type 配置项控制索引分片恢复的方式。恢复类型决定了分片数据如何从其他节点或本地存储恢复到当前节点。 配置项类型 # 该配置项为静态配置，需要在创建索引时设置。 默认值 # 空字符串（使用默认恢复方式） 是否必需 # 可选配置项（有默认值） 可选值 # 值 说明 空（默认） … - [缺少必需设置 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/missing-required-setting-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-6.8 1. 错误异常的基本描述 # 缺少必需设置 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [解析 Watch Status 时字段应为字符串却读到其他类型 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-watch-status-for-expecting-field-to-hold-a-string-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # could not parse watch status for [watchId]. expecting field [field] to hold a string value; found [token] instead 表示 Elasticsearch 在解析某个 Watch 的 status（执行状态）时，发现指定字段的值类 … - [读取搜索请求时出现未预期的数组字段 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-read-search-request-unexpected-array-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.x-8.x 1. 问题含义 # could not read search request. unexpected array field [field] 表示 Elasticsearch 在解析搜索请求时，遇到了一个顶层数组字段，但当前字段名不允许以数组形式出现。 这类错误和普通 JSON 语法错误不同，JSON 本身可能完全合法，只是字段契约不对。 2. 为什么会发生这个错 … - [路径中的无效元素 element in path path - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/invalid-path-element-element-in-path-path-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.2 1. 错误异常的基本描述 # 路径中的无效元素 element in path path 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接 … - [达到最大运行作业容量 localMaxAllowedRunningJobs - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/max-running-job-capacity-localmaxallowedrunningjobs-reached-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.2-7.15 1. 错误异常的基本描述 # 达到最大运行作业容量 localMaxAllowedRunningJobs 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常 … - [限流搜索线程池队列大小配置](https://easysearch.cn/knowledge-base/easysearch_config/thread_pool.search_throttled.queue_size/): 配置项作用 # thread_pool.search_throttled.queue_size 配置项用于控制限流搜索线程池的队列大小。 当所有限流搜索线程都在忙碌时，新的搜索请求会被放入队列等待。 配置项属性 # 配置路径: thread_pool.search_throttled.queue_size 数据类型: Integer（整数） 默认值: 100 是否可选: 是 作用域: … - [集群状态增量发布配置](https://easysearch.cn/knowledge-base/easysearch_config/discovery.zen.publish_diff.enable/): 配置项作用 # discovery.zen.publish_diff.enable 配置项用于控制主节点向集群其他节点发布集群状态时是否采用增量发布机制。 增量发布是指只发送集群状态中发生变化的部分，而不是发送完整的集群状态。 配置项属性 # 配置路径: discovery.zen.publish_diff.enable 数据类型: Boolean（布尔值） 默认值: true 是否可选: … - [could not parse pager duty event template unexpected field - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-pager-duty-event-template-unexpected-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # could not parse pager duty event template. unexpected field [field] 是 Elasticsearch Watcher 在解析 PagerDuty 事件模板时抛出的异常。当事件模板对象中出现当前解析器不支持的字段时，就会触发此错误。 此错误指向模板 JSON 结构本身，而不 … - [Easysearch 分页性能避坑指南：为什么 from_size 会慢？](https://easysearch.cn/knowledge-base/usage/easysearch-pagination-performance-guide/): 分页是几乎所有搜索应用都具备的基础功能。在数据量较小时，开发者习惯使用 from 和 size 参数进行翻页，这简单直观。然而，随着数据量增长和页码变深，查询响应时间往往呈指数级上升，甚至引发集群性能抖动。 本文将深入 Easysearch 的分布式原理，解释为什么深度分页会变慢，介绍平台内置的保护机制，并给出高效、稳定的替代方案。 原理：from/size 是如何工作的？ # … - [Easysearch 初印象：一款为国产化环境而生的轻量级搜索引擎](https://easysearch.cn/knowledge-base/basic/easysearch-first-impression-lightweight-search-engine/): 传统分布式搜索引擎常面临安装复杂、配置繁琐、国外技术依赖等痛点，在国产化浪潮下，企业亟需自主可控、简单易用且高性能的替代方案。 极限科技（INFINI Labs）推出的 INFINI Easysearch，正是为解决这些痛点而生的分布式搜索引擎，核心定位为“为国产化环境量身定制的轻量级分布式搜索引擎”。 一、Easysearch 是什么：轻量且全能的搜索新选择 # Easysearch 支持结构 … - [HTTP Content-Type 必需配置](https://easysearch.cn/knowledge-base/easysearch_config/http.content_type.required/): 配置项作用 # http.content_type.required 配置项强制要求 HTTP 请求必须包含有效的 Content-Type 头。 是否可选 # 否（此配置已弃用，始终为 true） 默认值 # true (强制要求 Content-Type) 配置项类型 # 已弃用 - 此配置项仅为滚动升级兼容性保留，实际值始终为 true 配置格式 # # 此配置已弃用， … - [inner collapse 结构解析失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/invalid-token-in-the-inner-collapse-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 当请求体里的 collapse 内部对象结构不合法时，解析阶段会抛出： Invalid token in the inner collapse 这类错误通常不是搜索执行失败，而是 DSL 在解析阶段就被拒绝了。 2. 为什么会发生这个错误 # collapse 的内部结构只能包含 Elasticsearch 认可的字段和对象层级。如果 … - [ISM 抖动因子配置](https://easysearch.cn/knowledge-base/easysearch_config/index_state_management.jitter/): 配置项作用 # index_state_management.jitter 配置项控制 ISM 协调器的随机抖动因子，用于分散多个节点的操作时间，避免同时执行造成的集群负载峰值。 是否可选 # 是 默认值 # 0.6 配置项类型 # 动态配置 - 可以在运行时修改 配置格式 # # 默认配置 index_state_management.jitter: 0.6 # … - [NAME 未找到类型的子类型 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/name-no-child-types-found-for-type-type-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-6.8 1. 错误异常的基本描述 # NAME 未找到类型的子类型 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [SimpleQueryStringBuilder NAME 查询文本缺失 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/simplequerystringbuilder-name-query-text-missing-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # SimpleQueryStringBuilder NAME 查询文本缺失 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现 … - [TermsQueryBuilder NAME unknown token - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/termsquerybuilder-name-unknown-token-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.6 1. 错误异常的基本描述 # [terms] unknown token [token] after [currentFieldName] 表示 Elasticsearch 在解析 terms 查询时，已经读到了某个字段名，但接下来出现的 JSON token 类型不符合 terms 查询允许的结构。 从页面中的源码看， … - [Username is a required option - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/username-is-a-required-option-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Username is a required option 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可 … - [创建 RunningStats 副本时出错 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/error-trying-to-create-a-copy-of-runningstats-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 创建 RunningStats 副本时出错 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [创建或更新安全用户](https://easysearch.cn/knowledge-base/easysearch_api/create-or-update-security-user/): 此 API 用于创建或更新 Easysearch 内部用户。 API # PUT /_security/user/{name} API 的作用 # 创建新的内部用户或更新已存在的用户配置。此 API 是 Easysearch 安全模块的一部分，用于管理系统用户账户。 API 的参数 # 路由参数 # 参数 类型 是否必需 描述 name string 必需 用户名 查询 … - [坐标未包含 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/coordinates-not-included-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 坐标未包含 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [多短语查询 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/multi-phrase-query-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.3-8.9 1. 错误异常的基本描述 # 多短语查询 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [导入规则库（指定ID覆盖）](https://easysearch.cn/knowledge-base/easysearch_api/import-ruleset-with-id-overwrite/): 将规则导入到指定的规则库中，使用覆盖模式。如果规则库已存在，将完全替换原有规则。 API 格式 # POST /_match_rules/{repo_id}/_import API 作用 # 该 API 用于将规则导入到指定的规则库（规则仓库）中： 覆盖模式：完全替换规则库中的现有规则 如果规则库不存在，则创建新的规则库 支持批量导入多条规则 自动管理规则库版本号 API 参数 # 路径 … - [文件系统慢路径日志阈值配置](https://easysearch.cn/knowledge-base/easysearch_config/monitor.fs.health.slow_path_logging_threshold/): 配置项作用 # monitor.fs.health.slow_path_logging_threshold 配置项用于控制文件系统健康检查操作超过多少时间会被记录为慢路径警告日志。 当文件系统健康检查操作（创建临时文件、写入数据、fsync 同步、删除文件）的执行时间超过此阈值时，系统会记录一条警告日志，提示某个数据路径的 IO 性能可能存在问题。 配置项属性 # 配置路径: … - [无法与机器学习原生代码通信 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-communicate-with-machine-learning-native-code-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.17 1. 错误异常的基本描述 # 无法与机器学习原生代码通信 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法在脚本字段上定义多字段 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-define-multifields-on-a-field-with-a-script-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.13-8.9 1. 错误异常的基本描述 # 无法在脚本字段上定义多字段 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法查找分数 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/couldn-t-look-up-score-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # 无法查找分数 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法访问搜索器管理器 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-access-searcher-manager-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 无法访问搜索器管理器 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [期望 START_OBJECT 但得到 parser.currentToken - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/expected-start-object-but-got-parser-currenttoken-how-to-solve-this-elasticsearch-exception/): 适用版本： 7-8.9 1. 错误异常的基本描述 # 期望 START_OBJECT 但得到 parser.currentToken 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 … - [校验和验证失败 - 期望值 0x - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/checksum-verification-failed-expected-0x-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # 校验和验证失败 - 期望值 0x 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [清扫器分页大小配置](https://easysearch.cn/knowledge-base/easysearch_config/jobscheduler.sweeper.page_size/): 配置项作用 # jobscheduler.sweeper.page_size 配置项用于控制作业清扫器（Job Sweeper）在扫描作业索引时每次搜索请求获取的文档数量。 清扫器负责定期扫描作业索引，确保调度的作业与集群状态同步。此配置决定了每次搜索请求返回的文档数量，影响清扫器的内存使用和网络开销。 配置项属性 # 配置路径: jobscheduler.sweeper.page_size … - [示例尚不支持管道符 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/samples-do-not-support-pipes-yet-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.6-8.9 1. 错误异常的基本描述 # 示例尚不支持管道符 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [缓存回收器页面类型配置](https://easysearch.cn/knowledge-base/easysearch_config/cache.recycler.page.type/): 配置项作用 # cache.recycler.page.type 配置项控制缓存回收器（Cache Recycler）的页面回收策略类型。缓存回收器负责管理内存页面的分配和回收，此配置决定了回收器的并发行为和性能特征。 配置项类型 # 该配置项为静态配置，需要在启动时设置，修改后需要重启节点才能生效。 默认值 # CONCURRENT 是否必需 # 可选配置项（有默认值） 取值范围 # … - [缓存策略未配置操作 cachingStrategy - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/no-action-configured-for-caching-strategy-cachingstrategy-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.17 1. 错误异常的基本描述 # 缓存策略未配置操作 cachingStrategy 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能 … - [输入JSON数据格式错误——如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/the-input-json-data-is-malformed-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 输入JSON数据格式错误— 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [非法的分片路由状态 (illegal_shard_routing_state_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/illegal_shard_routing_state_exception/): 为什么这个错误发生 # illegal_shard_routing_state_exception 表示分片路由状态与操作不匹配。 如何修复 # 1. 检查分片路由信息 # GET /_cat/shards?v&h=index,shard,prirep,state,node 2. 等待分片分配完成 # GET … - [预期 NESTED_FILTER_FIELD getPreferredName 元素 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/expected-nested-filter-field-getpreferredname-element-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.17 1. 错误异常的基本描述 # 预期 NESTED_FILTER_FIELD getPreferredName 元素 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起 … - [Debug PLAN should be specified at most once - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/debug-plan-should-be-specified-at-most-once-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Debug PLAN should be specified at most once 是 Elasticsearch SQL 模块在解析 DEBUG 语句时抛出的 ParsingException。当 SQL 文本中多次出现 PLAN 子句时，解析器会在语法分析阶段直接终止并报错。该异常属于语法解析错误，而非执行时错误，因此请求不会进 … - [Easysearch 是什么？一篇文章读懂国产企业级搜索引擎](https://easysearch.cn/knowledge-base/basic/what-is-easysearch-understanding-domestic-enterprise-search-engine/): 引言：国产搜索的破局者，生于时代需求 # 在搜索引擎技术发展的二十余年里，Lucene 奠定基础，Elasticsearch（简称 ES）成为企业级搜索的主流选择。但 2021 年 Elastic 变更开源协议为 SSPL，引发社区分裂与商业合规风险；叠加国际形势变化与国产化进程加速，国内企业亟需一款 “自主可控、兼容易用、性能可靠” 的替代方案。正是在这样的背景下，极限科技（INFINI … - [Easysearch 的全文搜索，和你想象的完全不一样](https://easysearch.cn/knowledge-base/usage/easysearch-full-text-search-not-what-you-imagine/): 一、打破认知：全文搜索不是 “模糊匹配” 的代名词 # 提到全文搜索，很多人会将其与 “模糊查询” 画等号，认为它不如精确匹配精准；而谈到精确匹配，又觉得它只能处理固定关键词。但 Easysearch 的全文搜索彻底颠覆了这种认知 —— 它既保留了全文检索的灵活性，又通过技术优化实现了超越传统精确匹配的精准度，甚至能智能理解搜索意图。 二、核心对决：全文搜索 vs 精确匹配的本质差异 # … - [fuzzy intervals query - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/fuzzy-intervals-query-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.3-8.9 1. 错误异常的基本描述 # fuzzy intervals query 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [host list for [key] is empty but type is [type] - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/host-list-for-key-is-empty-but-type-is-type-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.5-8.9 1. 错误异常的基本描述 # host list for [key] is empty but type is [type] 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一 … - [Incoming version – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/incoming-version-how-to-solve-this-elasticsearch-exception/): 适用版本： 7-7.15 1. 错误异常的基本描述 # Incoming version 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Labels 提示仅支持字符串值或字符串列表 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/labels-hint-supports-either-string-value-or-list-of-strings-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.3-8.9 1. 错误异常的基本描述 # Labels 提示仅支持字符串值或字符串列表 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Setting – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/setting-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # Setting 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [中断等待完成 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/interrupted-waiting-for-completion-of-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.6 1. 错误异常的基本描述 # 中断等待完成 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [分片不可用 (unavailable_shards_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/unavailable_shards_exception/): 为什么这个错误发生 # unavailable_shards_exception 表示所需的分片数量不可用，无法执行操作。 如何修复 # 1. 检查分片状态 # GET /_cat/shards?v 2. 等待分片恢复 # GET /_cluster/health?wait_for_active_shards=all 3. 调整副本设置 # PUT … - [前缀查询无法在特定条件下执行 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/prefix-queries-cannot-be-executed-when-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.7-7.15 1. 错误异常的基本描述 # 前缀查询无法在特定条件下执行 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [取消任务](https://easysearch.cn/knowledge-base/easysearch_api/cancel-task/): 此 API 用于取消集群中的一个或多个任务。 API # POST /_tasks/_cancel POST /_tasks/{task_id}/_cancel API 的作用 # 取消集群中正在执行的一个或多个任务。此 API 支持多种取消策略： 取消指定任务：通过 task_id 取消特定任务 按节点取消：取消特定节点上的所有任务 按类型取消：取消特定类型的任务 取消父任务：取消父任务及 … - [启动转换参数 getId 在超时后超时 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/starting-transform-params-getid-timed-out-after-timeout-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.6-8.4 1. 错误异常的基本描述 # 启动转换参数 getId 在超时后超时 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [字段维度数量错误 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/the-number-of-dimensions-for-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.3-7.15 1. 错误异常的基本描述 # 字段维度数量错误 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [收到无效时间 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/invalid-time-received-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 收到无效时间 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [数据主权时代：企业为什么要关注搜索引擎的“国籍”](https://easysearch.cn/knowledge-base/insight/data-sovereignty-era-why-enterprises-should-care-about-search-engine-nationality/): 当一家跨国科技企业试图将其亚洲业务数据回传到北美总部进行分析时，它被当地法规明确禁止。数据，如同新时代的“石油”，其流动的阀门已不再仅由技术或商业逻辑控制，而越来越多地受到数据主权所划定的无形国界制约。 我们正步入一个数据主权明确彰显的时代。国家、地区乃至企业，都在前所未有地强调对数据生成、存储、处理、传输和管理的控制权。在这一宏大背景下，作为企业数据核心处理引擎之一的搜索引擎，其研发主体、法律 … - [数据加密错误 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/error-encrypting-data-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 数据加密错误 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法从只读仓库删除快照——如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-delete-snapshot-from-a-readonly-repository-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # cannot delete snapshot from a readonly repository 是 Elasticsearch 在删除快照时抛出的仓库级异常。它发生在删除流程的最前端——Elasticsearch 在真正执行任何删除动作之前，会先检查目标仓库是否为只读；如果是，则立即抛出 RepositoryException，不 … - [无法从搜索命中中解析转换统计信息 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-transform-stats-from-search-hit-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.5-8.x 1. 错误异常的基本描述 # failed to parse transform stats from search hit 出现在 Transform 组件读取内部统计文档时。Elasticsearch 会从内部索引取回 _source，再调用 TransformStoredDoc.fromXContent 反序列化；如果文档结构不符合预期，就会抛出这个异常。 这 … - [无法在只读仓库上创建分片快照 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-snapshot-shard-on-a-readonly-repository-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.1-8.9 1. 错误异常的基本描述 # cannot snapshot shard on a readonly repository 表示 Elasticsearch 已经进入到分片快照写入流程，但发现目标仓库是只读的，因此无法继续把当前分片数据写入仓库。这个错误直接发生在 snapshot shard 的执行路径上，说明问题不在查询、不在分片分配本身，而在仓库写权限和仓库策 … - [无法打开 Job，因为没有足够容量的 ML 节点 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-open-job-because-no-ml-nodes-with-sufficient-capacity-were-found-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # Could not open job because no ML nodes with sufficient capacity were found 表示 Elasticsearch 在尝试打开一个机器学习 Job 时，集群中没有任何 ML 节点具备足够的资源来承载该 Job，因此 open 操作被拒绝，并返回 429 … - [无法解析响应体，它似乎不是 (Could not parse response body it does not appear to be) - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-response-body-it-does-not-appear-to-be-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # 无法解析响应体，它似乎不是 (Could not parse response body it does not appear to be) 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只 … - [构建fetch子阶段时出错 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/error-building-fetch-sub-phases-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.1-8.9 1. 错误异常的基本描述 # 构建fetch子阶段时出错 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [查询分片分配](https://easysearch.cn/knowledge-base/easysearch_api/get-shard-allocation/): 此 API 提供集群中每个数据节点的分片分配情况和磁盘使用状态的快照视图。 API # GET /_cat/allocation GET /_cat/allocation/{nodes} API 的作用 # 返回集群中各个节点的分片分配信息，包括： 分片数量：每个节点上分配的分片总数 磁盘使用：索引数据占用的磁盘空间 磁盘状态：已用、可用、总容量和使用百分比 节点信息：节点名称、IP 地址和 … - [模糊查询 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/fuzzy-query-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.3-8.9 1. 错误异常的基本描述 # 模糊查询 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [索引状态管理元数据服务启用配置](https://easysearch.cn/knowledge-base/easysearch_config/index_state_management.metadata_service.enabled/): 配置项作用 # index_state_management.metadata_service.enabled 配置项用于启用或禁用索引状态管理（ISM）的元数据服务。 配置项属性 # 配置路径: index_state_management.metadata_service.enabled 数据类型: Boolean（布尔值） 默认值: true 是否可选: 是 作用域: … - [缺少聚合定义 aggregationName – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/missing-definition-for-aggregation-aggregationname-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # 缺少聚合定义 aggregationName 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [脚本缓存大小配置](https://easysearch.cn/knowledge-base/easysearch_config/script.cache.max_size/): 配置项作用 # script.cache.max_size 配置项控制已编译脚本缓存的最大数量。脚本编译后会被缓存以便后续快速执行，此配置决定缓存可以容纳的脚本数量。 配置项类型 # 该配置项为动态配置，可以在运行时通过集群设置 API 进行修改。 默认值 # 100 是否必需 # 可选配置项（有默认值） 取值范围 # 0 ~ 正无穷 配置格式 # # … - [自动收缩投票配置](https://easysearch.cn/knowledge-base/easysearch_config/cluster.auto_shrink_voting_configuration/): 配置项作用 # cluster.auto_shrink_voting_configuration 配置项控制集群是否自动收缩投票配置（Voting Configuration）。当有资格作为主节点的节点加入或离开集群时，此配置决定系统是否自动调整投票配置以维持最佳的容错能力。 配置项类型 # 该配置项为动态配置，可以在运行时通过集群设置 API 进行修改。 默认值 # true 是否必需 # … - [节点 PID 文件配置](https://easysearch.cn/knowledge-base/easysearch_config/node.pidfile/): 配置项作用 # node.pidfile 配置项用于指定节点进程 ID（PID）文件的存储路径。 PID 文件包含运行中的 Easysearch 节点的进程 ID，用于进程管理和服务控制。当节点启动时，其 PID 会被写入指定的文件；当节点正常关闭时，文件会被删除。 配置项属性 # 配置路径: node.pidfile 数据类型: String（文件路径字符串） 默认值: 无（不创建 PID … - [解析 Action Status 时缺少必填字段 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-action-status-for-missing-required-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # could not parse action status for [actionId]. missing required field [field] 表示 Elasticsearch 在解析某个 Watcher Action 的状态对象时，发现缺少必需字段，导致解析失败。最常见的场景是 ack_status 字段缺失。 … - [过早到达文件末尾导致事务日志被截断 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/reached-premature-end-of-file-translog-is-truncated-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 过早到达文件末尾导致事务日志被截断 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [集群发现配置: unconfigured_bootstrap_timeout](https://easysearch.cn/knowledge-base/easysearch_config/discovery.unconfigured_bootstrap_timeout/): discovery.unconfigured_bootstrap_timeout 配置项控制集群发现相关行为。 配置格式 # # 默认配置 discovery.unconfigured_bootstrap_timeout: default - [需要操作员权限 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/operator-privileges-are-required-for-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.11-8.9 1. 错误异常的基本描述 # 需要操作员权限 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Easysearch 是如何把“搜不到”变成“秒出结果”的？](https://easysearch.cn/knowledge-base/basic/easysearch-how-to-turn-no-results-into-instant-results/): 对于许多开发者来说，实现一个“搜索”功能，最初的尝试往往是从一行 SQL 开始的： SELECT * FROM articles WHERE content LIKE '%搜索引擎%'; 这个查询在数据量小时尚可应付，但随着数据增长到十万、百万甚至上亿条，它会变成一场灾难：查询慢如蜗牛，结果的相关性一塌糊涂，甚至可能因为全表扫描而拖垮整个数据库。 你可能会问：为什么我手机相册里上万 … - [Foreach对象是空列表，无法执行任何操作 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/foreach-object-was-an-empty-list-could-not-run-any-action-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.3-8.9 1. 错误异常的基本描述 # Foreach对象是空列表，无法执行任何操作 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Geo字段不支持精确搜索，请使用专用地理查询 – 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/geo-fields-do-not-support-exact-searching-use-dedicated-geo-queries-instead-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.6 1. 错误异常的基本描述 # Geo字段不支持精确搜索，请使用专用地理查询 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [ID为request getId的任务不存在 – 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/the-task-with-id-request-getid-doesn-t-exist-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # ID为request getId的任务不存在 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [No handler for type – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/no-handler-for-type-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.11-7.15 1. 错误异常的基本描述 # No handler for type 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Shape must be an object consisting of type and coordinates – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/shape-must-be-an-object-consisting-of-type-and-coordinates-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Shape must be an object consisting of type and coordinates 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合 … - [SQL语句过大——如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/sql-statement-too-large-how-to-solve-this-elasticsearch-exception/): 适用版本： 7-7 1. 错误异常的基本描述 # SQL语句过大— 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返回 400、404、409、429、500 … - [Transport TCP Keep-Alive 空闲时间配置](https://easysearch.cn/knowledge-base/easysearch_config/transport.tcp.keep_idle/): 配置项作用 # transport.tcp.keep_idle 配置项用于控制TCP keep-alive 探测开始前的空闲时间（秒）。 配置项属性 # 配置路径: transport.tcp.keep_idle 数据类型: Integer（整数，秒） 默认值: -1（使用操作系统默认值） 是否可选: 是 作用域: NodeScope（节点级别） 动态更新: 否（需要重启节点生效） 配置建 … - [week schedule 的 times 不是对象 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-week-times-expected-an-object-but-found-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # could not parse week times. expected an object; but found [token] 是 Elasticsearch Watcher 定时任务调度配置中常见的解析异常。当 Elasticsearch 在解析 weekly 类型的 schedule（调度计划）时，期望 times … - [任务因原因 %s 被取消 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/task-cancelled-with-reason-s-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.4-8.9 1. 错误异常的基本描述 # 任务因原因 %s 被取消 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [内存锁定配置](https://easysearch.cn/knowledge-base/easysearch_config/bootstrap.memory_lock/): 配置项作用 # bootstrap.memory_lock 配置项控制是否锁定 JVM 内存，防止其被操作系统交换到磁盘（swap）。启用此配置可以提高 Easysearch 的性能和稳定性。 配置项类型 # 该配置项为静态配置，需要在启动时设置，修改后需要重启节点才能生效。 默认值 # false（不启用） 是否必需 # 可选配置项 工作原理 # 未启用内存锁定（默认）： JVM 堆内 … - [删除搜索管道](https://easysearch.cn/knowledge-base/easysearch_api/delete-search-pipeline/): 从集群中删除一个或多个搜索管道。 API 格式 # DELETE /_search/pipeline/{id} API 作用 # 该 API 用于从集群中删除搜索管道： 删除指定 ID 的搜索管道 支持通配符批量删除多个管道 删除后无法在搜索请求中使用该管道 API 参数 # 路径参数 # 参数 类型 是否必填 默认值 描述 {id} String 是 - 管道 ID，支 … - [只能对keyword和text字段使用regexp查询，而不能用于其他字段类型 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/can-only-use-regexp-queries-on-keyword-and-text-fields-not-on-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Can only use regexp queries on keyword and text fields - not on [xxx] which is of type [xxx] 是 Elasticsearch 中一个常见的查询类型不匹配异常。当你对不支持正则表达式查询的字段类型使用 regexp 查询 … - [字段不存在 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/field-field-does-not-exist-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 字段不存在 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [字段的未知值 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unknown-value-v-for-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.1-7.15 1. 错误异常的基本描述 # 字段的未知值 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [快照失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/snapshot-failed-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # snapshot failed 表示 Elasticsearch 在获取 shard 的 safeCommitRef 时抛出了异常，随后被包装成 RecoveryEngineException。这里的 snapshot 并不是仓库层 REST snapshot 请求本身，而是恢复/复制引擎为了后续数据传输而尝试获取一个安全提交点时失败。 … - [快照异常 (snapshot_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/snapshot_exception/): 为什么这个错误发生 # snapshot_exception 是一个通用的快照异常，表示在创建、恢复或管理快照时发生错误。 这个错误可能由以下原因引起： 仓库不可访问：快照仓库无法访问 磁盘空间不足：仓库磁盘空间不足 网络问题：与远程仓库的网络连接问题 快照正在进行：快照操作已在进行中 索引状态错误：索引状态不正确 权限问题：没有访问仓库的权限 快照已存在：尝试创建已存在的快照 分片未分配：部 … - [无法从空事务日志快照恢复 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-recover-from-empty-translog-snapshot-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 这条 failed to recover from empty translog snapshot 来自引擎恢复阶段。源码在持有读锁并确认 engine 处于 open 状态后，会执行 translogRecoveryRunner.run(this, Translog.Snapshot.EMPTY)。如果这个“空 translog 恢复 … - [无法加载设置中的文件 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/file-from-setting-cannot-be-loaded-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.7-7.15 1. 错误异常的基本描述 # 无法加载设置中的文件 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法获取事务日志的最早修改时间 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unable-to-get-the-earliest-last-modified-time-for-the-transaction-log-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 无法获取事务日志的最早修改时间 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法解析作业文档 hit.getId - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-job-document-hit-getid-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.x 1. 错误异常的基本描述 # failed to parse job document [hit.getId()] 出现在机器学习模块读取作业配置文档时。源码中会把搜索命中的 _source 交给 Job.LENIENT_PARSER 解析；如果命中内容不是合法的作业配置，就会抛出这个异常。 常见现象 # 查看 ML job、启动 job、恢复 anomaly … - [无法解析指定 ID 的 Watch - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-watch-with-id-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.x 1. 错误异常的基本描述 # Could not parse watch with id [<watch_id>] 表示 Elasticsearch 在读取某个已存在的 Watch 时，底层解析过程抛出了 IOException，于是又包装成当前异常。 这类错误常见于 加载存量 Watch，而不是新建请求体的即时校验失败。 2. 从日志可判断出的根因 # … - [最大投票配置排除数配置](https://easysearch.cn/knowledge-base/easysearch_config/cluster.max_voting_config_exclusions/): 配置项作用 # cluster.max_voting_config_exclusions 配置项控制集群中允许同时存在的投票配置排除（Voting Config Exclusions）的最大数量。投票配置排除用于从投票配置中临时移除节点，通常用于安全地从集群中移除节点或进行节点维护。 配置项类型 # 该配置项为动态配置，可以在运行时通过集群设置 API 进行修改。 默认值 # 10 … - [未知的星期几数字 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unknown-day-of-week-number-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 未知的星期几数字 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [查询安全角色](https://easysearch.cn/knowledge-base/easysearch_api/get-security-role/): 获取 Easysearch 中的安全角色配置信息。 API 格式 # GET /_security/role GET /_security/role/{name} API 作用 # 该 API 用于检索安全角色的配置信息： GET /_security/role：获取所有角色 GET /_security/role/{name}：获取指定角色 API 参数 # 路径参数 # … - [格式错误的正则表达式文件：对象后应该接数组——如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/malformed-regular-expression-file-should-continue-with-array-after-object-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 格式错误的正则表达式文件：对象后应该接数组— 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [清扫器退避延迟配置](https://easysearch.cn/knowledge-base/easysearch_config/jobscheduler.sweeper.backoff_millis/): 配置项作用 # jobscheduler.sweeper.backoff_millis 配置项用于控制作业清扫器（Job Sweeper）在执行搜索请求失败时的重试退避初始延迟时间。 当清扫器遇到可重试的错误（如 502 Bad Gateway、504 Gateway Timeout、503 Service Unavailable）时，会使用指数退避策略进行重试，此配置作为退避算法的起始延迟值。 … - [系统读取线程池配置](https://easysearch.cn/knowledge-base/easysearch_config/thread_pool.system_read/): 配置项作用 # thread_pool.system_read 相关配置项控制用于执行系统级别读取操作的线程池。系统读取操作包括内部系统管理、元数据读取等操作。该线程池采用固定大小线程池类型。 配置项类型 # 该配置项为静态配置，需要在启动时设置，修改后需要重启节点才能生效。 默认值 # thread_pool.system_read.size: half_processors_max_5 … - [索引未被完全快照，无法恢复 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/index-index-wasn-t-fully-snapshotted-cannot-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # index [index] wasn't fully snapshotted - cannot restore 表示当前要恢复的索引，在源快照里并没有完整快照成功，因此 Elasticsearch 拒绝执行完整恢复。 从源码逻辑看，只有当快照记录显示该索引失败且本次 restore 请求不是 partial 模式时，才会抛出这条异常。 … - [缺少JWT算法头 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/missing-jwt-algorithm-header-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # 缺少JWT算法头 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [聚合结果“看起来不对”？你可能忽略了这些细节](https://easysearch.cn/knowledge-base/usage/easysearch-aggregation-accuracy-details/): 在使用 Easysearch 做统计分析时，很多人都会遇到一个似曾相识的问题： “我这条聚合写得没问题，但结果总感觉不太对。” 文档数对不上、排行榜顺序异常、同一份数据在不同时间查询结果略有差异…… 这些现象往往不是 Bug，而是聚合本身的计算特性在起作用。 本文将从 Easysearch 的聚合机制出发，系统讲清楚聚合精度与近似这一经常被忽略、却非常关键的话题，帮助你在“结果不对”时，知道该从哪 … - [解析对象失败：意外结构——如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-object-unexpected-structure-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.2 1. 错误异常的基本描述 # 解析对象失败：意外结构— 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [读取搜索请求时遇到未预期对象字段 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-read-search-request-unexpected-object-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # could not read search request. unexpected object field [field] 表示 Elasticsearch 在解析搜索请求时，读到了一个不应出现在该层级的对象字段。 从保留代码看，这个位置本来只接受少数已知对象字段，例如 indices_options 或 template。 2. … - [非法纬度值 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/illegal-latitude-value-for-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # 非法纬度值 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [attempt to put missing mapping in indices - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/attempt-to-put-missing-mapping-in-indices-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # attempt to put missing mapping in indices [...] 是 Elasticsearch 在执行 PutMapping 操作时抛出的异常，表示集群尝试为一个或多个不存在的索引更新映射（mapping），导致操作无法完成。 该异常通常出现在使用 Elasticsearch 的高级功能（如跨集群搜索、数 … - [body missing for graph request - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/body-missing-for-graph-request-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9（Graph API 在 7.17+ 已标记为弃用，8.x 中部分版本已移除） 1. 错误异常的基本描述 # ElasticsearchParseException: Body missing for graph request 表示客户端向 Elasticsearch Graph API 的 _explore 端点发送了请求，但未携带请求体（request … - [boosting query requires positive query to be set - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/boosting-query-requires-positive-query-to-be-set-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # boosting query requires positive query to be set 是 Elasticsearch 在执行 Boosting Query 时抛出的参数校验异常。该错误明确表示：在构造 boosting 查询时，必须提供 positive（正查询）子句，但当前请求中缺失了该必填字段。 Boosting … - [could not parse message attachment field unexpected field - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-message-attachment-field-unexpected-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # could not parse message attachment field. unexpected field [field] 是 Elasticsearch Watcher 在解析消息附件（message attachment）对象时抛出的异常。当附件对象中出现当前解析器不支持的字段时，就会触发此错误。 … - [Disconnected – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/disconnected-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.3-8.9 1. 错误异常的基本描述 # Disconnected 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Easysearch：搜索结果高亮，是锦上添花还是性能杀手？](https://easysearch.cn/knowledge-base/usage/easysearch-search-highlighting-boon-or-performance-killer/): 一、Highlight 核心原理：注解驱动与原生语法适配 # Easysearch 的高亮功能基于 Lucene 底层机制独立实现，无需依赖第三方搜索引擎，其核心逻辑围绕三大技术支柱展开： 1. 底层技术基石 # 基于 Lucene 的 postings lists 倒排索引结构，通过精准记录关键词在文档中的位置偏移量，实现高亮文本的快速定位 支持原生 highlight 查询语法，启用需满 … - [EQL语句过大 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/eql-statement-is-too-large-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.7-7.15 1. 错误异常的基本描述 # EQL语句过大 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [GeometryCollection 包含此形状大小形状 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/geometrycollection-contains-this-shapes-size-shapes-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # GeometryCollection 包含此形状大小形状 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接 … - [HTTP TCP NoDelay 配置（已弃用）](https://easysearch.cn/knowledge-base/easysearch_config/http.tcp_no_delay/): 配置项作用 # http.tcp_no_delay 配置项用于控制是否禁用 TCP Nagle 算法。 ⚠️ 此配置已被弃用，请使用新版配置 http.tcp.no_delay。 配置项属性 # 配置路径: http.tcp_no_delay 数据类型: Boolean（布尔值） 默认值: true 是否可选: 是 作用域: NodeScope（节点级别） 弃用状态: ⚠️ 已弃用 配置项 … - [RecoverFromTranslog – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/recoverfromtranslog-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.9-8.9 1. 错误异常的基本描述 # RecoverFromTranslog 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [watch 的 input 必须是对象 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-input-for-watch-expected-an-object-representing-input-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # could not parse input for watch [id]. expected an object representing input [type]; but found [token] instead 表示 Watcher 已经识别出 input 类型名，但该类型后面没有跟一个对象结构。 2. … - [watch 的 simple input 必须是对象 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-input-for-watch-expected-an-object-but-found-instead-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.x 1. 错误异常的基本描述 # could not parse [simple] input for watch [<watch_id>]. expected an object but found [<token>] instead 是 Elasticsearch Watcher 在解析 Watch 定义时抛出的异常。 … - [内存断路器 Accounting 开销系数配置](https://easysearch.cn/knowledge-base/easysearch_config/indices.breaker.accounting.overhead/): 配置项作用 # indices.breaker.accounting.overhead 配置项用于控制Accounting 断路器在估算内存使用时的开销系数。 实际内存估算值 = 原始字节数 × 开销系数。这个系数用于补偿内存估算的不准确性，为系统提供额外的安全缓冲。 配置项属性 # 配置路径: indices.breaker.accounting.overhead 数据类型: … - [别名 aliasName 不存在 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/alias-aliasname-doesn-t-exist-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.14-8.9 1. 错误异常的基本描述 # alias [aliasName] doesn't exist 是 Elasticsearch 中常见的别名相关异常，表示当前操作引用的别名在集群中不存在。该错误通常发生在查询、写入、别名管理或数据流操作过程中，直接影响请求的可用性。 常见现象 # 执行搜索或写入请求时，Elasticsearch 返回 404 Not … - [字段匹配到多种点格式——如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/fields-matching-more-than-one-point-format-found-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.2-8.9 1. 错误异常的基本描述 # 字段匹配到多种点格式— 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [强制插件配置](https://easysearch.cn/knowledge-base/easysearch_config/plugin.mandatory/): 配置项作用 # plugin.mandatory 配置项用于指定必须存在的插件列表。 如果配置了强制插件列表，节点在启动时会检查所有指定的插件是否都已安装和加载。如果任何强制插件缺失，节点将拒绝启动并抛出异常。这确保了关键插件（如安全插件）始终存在，防止配置错误导致的安全风险。 配置项属性 # 配置路径: plugin.mandatory 数据类型: List<String>（插 … - [打开索引](https://easysearch.cn/knowledge-base/easysearch_api/open-index/): 打开一个或多个已关闭的索引，使其恢复正常功能。 API # POST /{index}/_open POST /_all/_open API 的作用 # 该 API 用于打开已关闭的索引。关闭的索引不会响应读写请求，也不会占用集群资源。使用 _open API 可以： 重新打开关闭的索引 恢复索引的读写操作 重新分配索引的分片 使索引可以正常被搜索 关闭 vs 打开索引 # 状态 … - [搜索是如何“听懂”你的？从自然语言理解到用户意图](https://easysearch.cn/knowledge-base/basic/how-search-understands-your-intent-nlp-guide/): 当我们在搜索框里输入一句话时，往往希望系统立刻明白我们的意思： 是想找资料？解决问题？还是做出某个决定？ 表面上看，我们只是输入了一串文字；但在搜索系统眼中，这是一种“人类语言”，而理解它，正是自然语言理解与搜索系统的交汇点。 一、搜索真的“懂你”吗？ # 先说一个事实： 搜索并不是在“理解你”，而是在“尽量接近理解你”。 搜索系统并没有意识，也不会真正理解语言背后的情感和动机。它所做的，是通 … - [无法从根blob确定仓库代数 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-determine-repository-generation-from-root-blobs-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.4-8.9 1. 错误异常的基本描述 # Could not determine repository generation from root blobs 表示 Elasticsearch 在扫描仓库根目录时，无法确定当前最新的 repository generation。按照快照仓库实现，系统通常会从根目录中的 index-N blobs 推断最新一代元数据；如果这一步失 … - [无法对 GEO_SHAPE 进行取整 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/can-t-round-a-geo-shape-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.9-8.9 1. 错误异常的基本描述 # can't round a [geo_shape] 是 Elasticsearch 在执行聚合（Aggregation）阶段抛出的 AggregationExecutionException。该异常的核心含义是：当前聚合器试图对 geo_shape 类型的字段值执行取整（rounding）操作，但该操作对地理形状数据类型不适用。 … - [无法恢复索引 index 因为它无法升级 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-restore-index-index-because-it-cannot-be-upgraded-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.14-8.9 1. 错误异常的基本描述 # cannot restore index [index] because it cannot be upgraded 表示 Elasticsearch 已经拿到了目标索引的 snapshot metadata，并尝试通过 indexMetadataVerifier.verifyIndexMetadata(...) 对它做版本兼容升级校 … - [无法获取SSL服务 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-obtain-ssl-service-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.8-8.9 1. 错误异常的基本描述 # 无法获取SSL服务 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法调整临时汇总索引 tmpIndexName 的大小 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unable-to-resize-temp-rollup-index-tmpindexname-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.12-8.2 1. 错误异常的基本描述 # 无法调整临时汇总索引 tmpIndexName 的大小 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返 … - [期望分配 ID 但发现不匹配 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/expected-allocation-id-but-found-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # 期望分配 ID 但发现不匹配 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [期望地理位置点——如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/geo-point-expected-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # 期望地理位置点— 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [检索用户失败，期望对象但得到了 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-retrieve-users-expecting-an-object-but-got-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.17 1. 错误异常的基本描述 # 检索用户失败，期望对象但得到了 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [清除缓存失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/clearing-the-cache-for-how-to-solve-this-elasticsearch-exception/): 适用版本： Elasticsearch 6.8 - 8.9（含 X-Pack Security 或 SearchGuard 等安全插件） 1. 错误异常的基本描述 # clearing the cache for [...] failed 是 Elasticsearch 安全模块在尝试清除用户领域（Realm）缓存时触发的异常。该错误通常出现在以下场景： … - [物理文件名 physicalName 缺失或无效 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/missing-or-invalid-physical-file-name-physicalname-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # 在快照恢复或底层文件元数据解析过程中，如果 physicalName 缺失或不合法，会报： missing or invalid physical file name [physicalName] 2. 为什么会发生这个错误 # 这类异常来自 FileInfo / StoreFileMetadata 解析，不是普通搜索请求问题。源码 … - [索引文档](https://easysearch.cn/knowledge-base/easysearch_api/index-document/): 向指定索引中索引（添加或更新）文档。 API # POST /{index}/_doc PUT /{index}/_doc POST /{index}/_doc/{id} PUT /{index}/_doc/{id} API 的作用 # 该 API 用于向索引中添加或更新文档，是 Easysearch 中最核心的数据写入操作。 操作类型 # … - [索引目录 indexPath 必须存在且为目录 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/index-directory-indexpath-must-exist-and-be-a-directory-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 索引目录 indexPath 必须存在且为目录 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返 … - [获取阶段执行失败 (fetch_phase_execution_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/fetch_phase_execution_exception/): 为什么这个错误发生 # fetch_phase_execution_exception 表示搜索的获取阶段失败，该阶段负责获取匹配文档的完整数据。 如何修复 # 1. 检查分片状态 # GET /_cat/shards?v 2. 简化查询 # 减少 _source 字段或使用 stored_fields。 3. 检查文档是否存在 # 某些文档可能已在查询后被删除。 4. 重试搜索 # … - [跨集群复制领导者线程池大小配置](https://easysearch.cn/knowledge-base/easysearch_config/replication_leader.size/): 配置项作用 # replication_leader.size 配置项用于控制复制领导者线程池的线程数量。 配置项属性 # 配置路径: replication_leader.size 数据类型: Integer（整数） 默认值: 0（自动计算为 (available_processors × 3/2) + 1） 是否可选: 是 作用域: NodeScope（节点级别） 动态更新: 是（可以动 … - [通用线程池配置](https://easysearch.cn/knowledge-base/easysearch_config/thread_pool.generic/): 配置项作用 # thread_pool.generic 配置项控制通用线程池（Generic ThreadPool）的大小和行为。通用线程池用于处理各种通用的异步操作，如节点间通信、集群状态更新、通用后台任务等。 配置项类型 # 该配置项为静态配置，需要在启动时设置，修改后需要重启节点才能生效。 默认值 # 核心线程数: 4 最大线程数: min(4 × CPU核心数, 512) … - [预期得到点列表但只得到了一个点 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/expected-a-list-of-points-but-got-a-point-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.2-8.9 1. 错误异常的基本描述 # 预期得到点列表但只得到了一个点 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [actual shard is not a primary - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/actual-shard-is-not-a-primary-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9+ 1. 错误异常的基本描述 # actual shard is not a primary 是 Elasticsearch 在分片路由或写入操作时抛出的分片状态错误。当你尝试在某个分片上执行只有**主分片（primary shard）才能执行的操作（如某些恢复操作、特定管理操作等），但实际路由到的分片是副本分片（replica shard）**时，就会触发此错 … - [Bad regex in setting cors allow origin - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/bad-regex-in-setting-cors-allow-origin-getkey-origin-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Bad regex in [http.cors.allow-origin] 是 Elasticsearch 在解析 CORS（跨域资源共享）配置时抛出的异常。当 Elasticsearch 的 http.cors.allow-origin 配置项中的正则表达式语法不合法时，节点启动或动态更新配置的过程中会触发此错误，导致 HTTP 服务 … - [connection manager is closed - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/connection-manager-is-closed-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.17-8.9 1. 错误异常的基本描述 # connection manager is closed 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能 … - [Easysearch Rollup 详解](https://easysearch.cn/knowledge-base/usage/easysearch-rollup-data-aggregation-guide/): 在海量日志（Logs）和指标（Metrics）场景下，随着时间推移，详细数据的存储成本会呈线性甚至指数级增长。然而，业务对于历史数据的查询需求往往不再需要精确到“毫秒级”的明细，而是关注“小时级”或“天级”的趋势统计。 INFINI Easysearch 内置的 Rollup（数据汇总）功能，通过将细粒度的历史数据定期“上卷”为粗粒度的统计摘要，能够将存储成本降低 90% 以上，同时保持秒级的查询 … - [Exception when deleting blobs [failedBlobs] - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/exception-when-deleting-blobs-failedblobs-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.6-7.17 1. 错误异常的基本描述 # 这条异常说明 Elasticsearch 在删除仓库中的一批 blob 时，failedBlobs 这一组对象没有删除成功。它通常出现在快照清理、仓库维护或删除遗留对象的阶段。 常见现象 # cleanup 或快照删除过程失败。 日志中带有失败对象列表或下层 IOException。 仓库可能部分删除成功，部分对象残留。 典型报 … - [failed to perform snapshot (index files) - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-perform-snapshot-index-files-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.5 1. 错误异常的基本描述 # failed to perform snapshot (index files) 表示 Elasticsearch 在执行分片快照时，处理索引文件这一阶段失败了。 从异常名看，这不是快照元数据初始化失败，而是已经进入 shard 文件快照流程，准备读取本地 Lucene 文件并写入 repository 时出错。 常见现象 # … - [failed to serialize XContent of field [field] - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-serialize-xcontent-of-field-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # failed to serialize XContent of field [field] 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态 … - [HTTP 详细错误信息配置](https://easysearch.cn/knowledge-base/easysearch_config/http.detailed_errors.enabled/): 配置项作用 # http.detailed_errors.enabled 配置项控制是否在 HTTP 错误响应中包含详细的调试信息。 是否可选 # 是 默认值 # true (启用详细错误信息) 配置项类型 # 静态配置 - 需要重启节点才能生效 配置格式 # # 启用详细错误（默认） http.detailed_errors.enabled: true # … - [ICU 规则文件加载失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-load-icu-rule-files-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # failed to load ICU rule files 出现在 org.elasticsearch.analysis.icu.IcuTokenizerFactory 等组件初始化阶段。日志上下文已明确出现 FileNotFoundException，说明问题通常发生在插件读取规则文件时，而不是查询执行阶段。 常见现象 # 创建索 … - [Lucene 与传统关系数据库](https://easysearch.cn/knowledge-base/basic/lucene-vs-relational-database-comparison/): 用户数量的增长都可能拉低应用程序的性能。因此，应用程序可能要求从数据库体系迁移到搜索架构体系，比如 Elasticsearch、 Easysearch。 Lucene 是一种全文搜索引擎，它与传统关系数据库的本质差异在于它们的底层数据结构不同。Lucene 的底层数据结构是倒排索引结构，而传统关系数据库的底层数据结构通常是** B 树或 B+ 树组织的正向聚集索引和非聚集索引结构**。 … - [Nested类型不支持subobjects参数 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/nested-type-name-does-not-support-subobjects-parameter-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.3-8.9 1. 错误异常的基本描述 # Nested类型不支持subobjects参数 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [PagerDuty 账户缺少必需的 service key - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/invalid-pagerduty-account-name-missing-required-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # invalid pagerduty account [name]. missing required [service_key] setting 是 Elasticsearch Watcher 在初始化 PagerDuty 告警动作时抛出的配置异常。当 Elasticsearch 尝试为指定的 PagerDuty … - [Profile uid 不包含区分符 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/profile-uid-does-not-contain-a-differentiator-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.2-8.9 1. 错误异常的基本描述 # Profile uid 不包含区分符 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [SSL TrustManager 初始化失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-initialize-ssl-trustmanager-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.4-7.17 1. 错误异常的基本描述 # SSL TrustManager 初始化失败 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Transform 内部索引重试次数配置](https://easysearch.cn/knowledge-base/easysearch_config/transform.internal.index.backoff_count/): 配置项作用 # transform.internal.index.backoff_count 配置项用于控制Transform 任务在索引操作失败时的重试次数。 配置项属性 # 配置路径: transform.internal.index.backoff_count 数据类型: Integer（整数） 默认值: 5 是否可选: 是 作用域: NodeScope（节点级别） 动态更新: 是（可 … - [Transport 发布端口配置](https://easysearch.cn/knowledge-base/easysearch_config/transport.publish_port/): 配置项作用 # transport.publish_port 配置项用于控制节点向其他节点和客户端宣告的端口号。 配置项属性 # 配置路径: transport.publish_port 数据类型: Integer（整数） 默认值: -1（使用实际监听端口） 是否可选: 是 作用域: NodeScope（节点级别） 动态更新: 否（需要重启节点生效） 配置建议 # 默认配置 # … - [Value must be of type String parameterName - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/value-must-be-of-type-string-parametername-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Value must be of type String parameterName 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判 … - [主机未在设置中列入白名单 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/host-host-is-not-whitelisted-in-setting-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # 主机未在设置中列入白名单 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [仅允许可以打开的存储或在打开时抛出 ShardLockObtainFailedException 的存储，但得到了 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/only-allow-store-that-can-be-opened-or-that-throws-a-shardlockobtainfailedexception-while-being-opened-but-got-a-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 仅允许可以打开的存储或在打开时抛出 ShardLockObtainFailedException 的存储，但得到了 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结 … - [创建数据流](https://easysearch.cn/knowledge-base/easysearch_api/create-data-stream/): 数据流（Data Stream）是 Easysearch 中专门用于管理时间序列数据（如日志、事件和指标）的机制。数据流内部由多个底层索引组成，支持自动滚动（rollover）和生命周期管理。 API # PUT /_data_stream/{name} API 的作用 # 创建数据流用于存储时间序列数据。数据流的主要特点包括： 自动滚动管理：当满足特定条件（如文档数量、大小或时间）时，自动 … - [发布失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/publication-failed-how-to-solve-this-elasticsearch-exception/): 适用版本： 7-8.7 1. 错误异常的基本描述 # 发布失败 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返回 400、404、409、429、500 … - [对象解析失败：应为 START_OBJECT 却收到其他 token - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-object-expected-start-object-but-was-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.2-8.9 1. 错误异常的基本描述 # 当解析 JSON/DSL 时，某个位置要求对象，但实际收到其他 token，会出现： Failed to parse object: Expected START_OBJECT but was: VALUE_STRING 也可能是别的 token，例如数组或数字。 2. 为什么会发生这个错误 # 这个错误本质上是 JSON 结构类型不 … - [嵌套对象映射的include_in_parent参数无法更新 – 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/the-include-in-parent-parameter-can-t-be-updated-for-the-nested-object-mapping-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.8-7.8 1. 错误异常的基本描述 # 嵌套对象映射的include_in_parent参数无法更新 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [序列化事件数据时发生意外错误](https://easysearch.cn/knowledge-base/elasticsearch_error/unexpected-error-while-serializing-event-data-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.11-8.9 1. 错误异常的基本描述 # 序列化事件数据时发生意外错误 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法从索引 blob 读取仓库数据 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/Could-not-read-repository-data-from-index-blob-How-to-solve-this-Elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # Could not read repository data from index blob 表示 Elasticsearch 在读取仓库元数据时，无法从 repository 的 index-N blob 中加载 RepositoryData。这里的 index blob 是快照仓库的核心索引文件， … - [无法修改字段名称的 doc_values 设置 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/setting-doc-values-cannot-be-modified-for-field-name-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.9 1. 错误异常的基本描述 # 无法修改字段名称的 doc_values 设置 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法解析 HTTP 请求附件 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-http-request-attachment-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Could not parse http request attachment 表示 Elasticsearch 在解析 Watcher 的 HTTP 附件定义时失败。 从保留日志看，外层是 ElasticsearchParseException，底层通常还会带一个 JsonParseException 或类似语法错误。 2. 为什么会 … - [无法解析可组合模板 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unable-to-parse-composable-template-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.9-8.9 1. 错误异常的基本描述 # 无法解析可组合模板 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [比值应在 0-1.0 范围内，得到 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/ratio-should-be-in-0-1.0-got-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 比值应在 0-1.0 范围内，得到 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [管道不支持 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/pipe-is-not-supported-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.13-8.9 1. 错误异常的基本描述 # 管道不支持 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [节点本地存储配置](https://easysearch.cn/knowledge-base/easysearch_config/node.local_storage/): 配置项作用 # node.local_storage 配置项用于控制节点是否允许将元数据等数据持久化到本地磁盘。 此设置不影响节点是否存储实际的索引数据（由 node.data 控制），但如果 node.local_storage 设置为 false，则 node.data 和 node.master 也必须为 false。 注意：此配置项已被废弃，推荐使用 node.roles 配置来替代。 … - [获取完全失败 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/total-failure-in-fetching-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 获取完全失败 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [获取节点使用情况](https://easysearch.cn/knowledge-base/easysearch_api/get-node-usage/): 获取集群中各个节点的使用情况统计信息，特别是 REST API 的调用统计和聚合器使用统计。 API # GET /_cluster/nodes/usage GET /_nodes/usage GET /_nodes/{nodeId}/usage GET /_nodes/usage/{metric} GET /_nodes/{nodeId}/usage/{metric} API 的作用 # … - [资源已存在 (resource_already_exists_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/resource_already_exists_exception/): 为什么这个错误发生 # resource_already_exists_exception 表示尝试创建一个已经存在的资源，如索引、模板、别名等。 这个错误可能由以下原因引起： 索引已存在：尝试创建同名的索引 别名已存在：尝试创建已存在的别名 模板已存在：尝试创建已存在的索引模板 管道已存在：尝试创建已存在的 Ingest 管道 重复创建：代码逻辑问题导致重复创建 并发操作：多个进程同时创建同 … - [运行时字段设置为null但不支持删除 – 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/runtime-field-fieldname-was-set-to-null-but-its-removal-is-not-supported-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.12-7.15 1. 错误异常的基本描述 # 运行时字段设置为null但不支持删除 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [集群发现配置: probe.handshake_timeout](https://easysearch.cn/knowledge-base/easysearch_config/discovery.probe.handshake_timeout/): discovery.probe.handshake_timeout 配置项控制集群发现相关行为。 配置格式 # # 默认配置 discovery.probe.handshake_timeout: default - [access key option is required for cleaning up s3 repository - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/access-key-option-is-required-for-cleaning-up-s3-repository-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.4-7.17+ 1. 错误异常的基本描述 # access_key option is required for cleaning up s3 repository 是 Elasticsearch 在执行 **S3 仓库清理（cleanup）**时抛出的凭证验证错误。当你尝试清理 S3 仓库（snapshot repository）的旧快照数据， … - [already waiting for a cluster state change - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/already-waiting-for-a-cluster-state-change-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9+ 1. 错误异常的基本描述 # already waiting for a cluster state change 是 Elasticsearch 的集群状态更新机制抛出的并发控制错误。当你尝试执行一个需要等待集群状态更新（如分片分配、索引创建、设置更新等）的操作，但已经有一个线程在等待集群状态更改时，就会触发此错误。Elasticsearch 的集群状态更新是串 … - [CONTENT TYPE 字段不支持搜索 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/content-type-field-do-not-support-searching-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # CONTENT TYPE 字段不支持搜索 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [context mapping 缺少必填参数 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/missing-paramname-in-context-mapping-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # missing [paramName] in context mapping 是 Elasticsearch 在解析 suggester 的 context mapping 配置时抛出的 ElasticsearchParseException。该错误表示在定义 suggester 的上下文映射（context mapping）时，某个必 … - [Easysearch：text 和 keyword 的区别，新手 90% 都理解错了](https://easysearch.cn/knowledge-base/usage/easysearch-text-vs-keyword-difference-90-percent-beginners-wrong/): 一、字段类型核心差异（新手最易踩坑点） # 对比维度 text 字段 keyword 字段 分词处理 索引时通过分析器（如 IK、标准分词）拆分文本，支持中文 / 多语种分词 📝"Apple iPhone 15 Pro" → [“apple”, “iphone”, “15”, … - [Expected 异常 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/expected-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Expected 异常 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [HTTP 警告头数量限制配置](https://easysearch.cn/knowledge-base/easysearch_config/http.max_warning_header_count/): 配置项作用 # http.max_warning_header_count 配置项控制 HTTP 响应中允许处理的最大警告头数量。 默认值 # -1（无限制） 配置类型 # 静态配置 取值范围 # -1 或 正整数 配置格式 # # 默认配置：无限制 http.max_warning_header_header_count: -1 # … - [HTTP 默认传输类型配置](https://easysearch.cn/knowledge-base/easysearch_config/http.type.default/): 配置项作用 # http.type.default 配置项指定默认的 HTTP 传输类型实现。 默认值 # netty4 配置类型 # 静态配置 配置格式 # # 默认配置 http.type.default: netty4 注意事项 # 重启生效：修改此配置需要重启节点 Easysearch 主要使用 Netty4 实现 通常不需要修改此配置 - [Key settings 必须是一个对象 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/key-settings-must-be-an-object-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.4-8.9 1. 错误异常的基本描述 # Key settings 必须是一个对象 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [OpenSearch 和 Easysearch：兼容性与生态差异详解](https://easysearch.cn/knowledge-base/basic/opensearch-easysearch-compatibility-ecosystem-differences/): 在当前的搜索引擎技术版图中，随着企业对自主可控、成本优化及云原生需求的日益增长，原本由 Elasticsearch 一统天下的局面正在发生变化。除了 Elasticsearch 本身，AWS 推出的 OpenSearch 和极限科技（INFINI Labs）打造的 Easysearch 成为了备受关注的两个重要分支。 尽管 OpenSearch 和 Easysearch … - [Rounding can only be used on single unit types – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/rounding-can-only-be-used-on-single-unit-types-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Rounding can only be used on single unit types 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状 … - [TCP Keepalive 探测间隔配置](https://easysearch.cn/knowledge-base/easysearch_config/network.tcp.keep_interval/): 配置项作用 # network.tcp.keep_interval 配置项用于控制TCP keepalive 探测包之间的间隔时间。 当启用 TCP keepalive 后，如果连接空闲（没有收到响应），系统会按照此间隔持续发送 keepalive probe 来检测连接状态。 配置项属性 # 配置路径: network.tcp.keep_interval 数据类型: Integer（整数， … - [事务日志异常 (translog_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/translog_exception/): 为什么这个错误发生 # translog_exception 是与事务日志（translog）相关的通用异常。事务日志用于保证数据操作的 durability，记录所有未刷新到磁盘的操作。 这个错误可能由以下原因引起： 事务日志损坏：translog 文件损坏或格式错误 写入失败：写入 translog 时磁盘空间不足或 I/O 错误 读取失败：读取 translog 恢复数据时失败 文件锁 … - [从...接收到集群状态 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/received-cluster-state-from-how-to-solve-this-elasticsearch-exception/): 适用版本： 7-7.15 1. 错误异常的基本描述 # 从...接收到集群状态 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [作业调度器抖动限制配置](https://easysearch.cn/knowledge-base/easysearch_config/jobscheduler.jitter_limit/): 配置项作用 # jobscheduler.jitter_limit 配置项用于控制作业调度器在调度作业时添加的随机抖动延迟的最大比例。 抖动（Jitter）是一种随机化技术，用于避免多个作业在同一时间点同时执行，防止系统负载突发。当作业执行间隔为 X 分钟时，下次作业执行会在当前时间点的基础上随机延迟 0 到 X × jitter_limit 分钟。 配置项属性 # 配置路径: … - [全局聚合器执行失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-execute-global-aggregators-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # 全局聚合器执行失败 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [列出 Blob 失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-list-blobs-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 这条 failed to list blobs 出现在 shard snapshot 相关文件列举阶段。源码中如果没有明确的 generation，Elasticsearch 会去执行 shardContainer.listBlobsByPrefix(INDEX_FILE_PREFIX) 来查找分片快照索引文件； … - [删除安全用户](https://easysearch.cn/knowledge-base/easysearch_api/delete-security-user/): 从 Easysearch 安全配置中删除指定的内部用户。 API 格式 # DELETE /_security/user/{name} API 作用 # 该 API 用于从内部原生领域（Native Realm）中删除用户，包括： 删除用户的所有关联数据（角色、属性、凭证） 更新整个集群的安全配置 需要相应的写权限 API 参数 # 路径参数 # 参数 类型 是否必填 默认值 描 … - [在等待投票配置排除时集群服务关闭 – 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cluster-service-closed-while-waiting-for-voting-config-exclusions-how-to-solve-this-elasticsearch-exception/): 适用版本： 7-7.15 1. 错误异常的基本描述 # 在等待投票配置排除时集群服务关闭 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [找不到 Model Alias - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/model-alias-could-not-be-found-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.13-8.9 1. 错误异常的基本描述 # model_alias could not be found 表示在执行 Trained Model Alias 相关操作时，Elasticsearch 无法在当前的别名元数据中找到指定的别名。该异常属于 ElasticsearchStatusException，返回状态码为 404 Not Found。 需要特别注意的是，这个异常不 … - [无法从本地分片恢复 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-recover-from-local-shards-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 无法从本地分片恢复 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法克隆索引 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/can-t-clone-index-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.1-7.13 1. 错误异常的基本描述 # 无法克隆索引 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法删除作业 jobgetId 的过期结果 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-remove-expired-results-for-job-job-getid-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 无法删除作业 jobgetId 的过期结果 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法检索检查点信息 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-retrieve-checkpointing-info-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.2-8.9 1. 错误异常的基本描述 # 无法检索检查点信息 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [更新设置后重新路由失败——如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/reroute-after-update-settings-failed-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 更新设置后重新路由失败— 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [查询指定摄入管道](https://easysearch.cn/knowledge-base/easysearch_api/get-specific-ingest-pipeline/): 获取一个或多个指定摄入管道的配置信息。 API 格式 # GET /_ingest/pipeline/{id} API 作用 # 该 API 用于检索摄入管道的配置信息： 获取指定 ID 的管道配置 支持逗号分隔的多个管道 ID 支持通配符模式匹配 查看管道描述和处理器列表 API 参数 # 路径参数 # 参数 类型 是否必填 默认值 描述 {id} String 是 - … - [管道尚不支持 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/pipe-is-not-supported-yet-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.9-7.12 1. 错误异常的基本描述 # 管道尚不支持 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [索引不存在且MapperService INDEX MAPPER DYNAMIC SETTING getKey为false——如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/no-such-index-and-mapperservice-index-mapper-dynamic-setting-getkey-is-false-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-6.8 1. 错误异常的基本描述 # 索引不存在且MapperService INDEX MAPPER DYNAMIC SETTING getKey为false— 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还 … - [缺少 explanation value - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/missing-explanation-value-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.x 1. 错误说明 # missing explanation value 是 Elasticsearch 在解析 Explanation 结构时抛出的 ParsingException。Explanation 是 Elasticsearch 用来描述文档评分计算过程的结构体，包含三个核心字段：value（评分数值）、description（评分描述） … - [获取URI失败 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/get-uri-failed-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.2-8.9 1. 错误异常的基本描述 # 获取URI失败 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [解析通配符正则表达式片段错误 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/error-parsing-wildcard-regex-pattern-fragment-fragment-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.9-8.9 1. 错误异常的基本描述 # 解析通配符正则表达式片段错误 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [通配符间隔查询](https://easysearch.cn/knowledge-base/elasticsearch_error/wildcard-intervals-query-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.3-8.9 1. 错误异常的基本描述 # 通配符间隔查询 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [集群发现配置: seed_resolver.max_concurrent_resolvers](https://easysearch.cn/knowledge-base/easysearch_config/discovery.seed_resolver.max_concurrent_resolvers/): discovery.seed_resolver.max_concurrent_resolvers 配置项控制集群发现相关行为。 配置格式 # # 默认配置 discovery.seed_resolver.max_concurrent_resolvers: default - [And 必须是有效的浮点值 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/and-must-be-valid-float-values-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.8-8.9 1. 错误异常的基本描述 # [x] and [y] must be valid float values 是 Elasticsearch 在解析空间数据类型（如 geo_point、geo_shape、shape 及 point 等笛卡尔坐标系类型）时抛出的解析异常。当请求体中包含的坐标值无法被转换为合法的浮点数时，Elasticsearch 会在查询或写入阶段直 … - [cannot find an key aggname in name - 聚合结果中找不到指定 key 如何解决](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-find-an-key-aggname-in-name-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.4-8.9 1. 错误异常的基本描述 # Cannot find an key [aggName] in [name] 表示 Elasticsearch 在某个多 bucket 聚合（如 terms、histogram 等）中按 key 查找 bucket 时，没有找到你指定的那个 key，于是抛出了路径错误。这通常发生在使用属性路径（property path） … - [Easysearch vs PostgreSQL GIN 索引：日志分析场景下的深度对决](https://easysearch.cn/knowledge-base/basic/easysearch-vs-postgresql-gin-index-log-analysis-comparison/): 在现代数据处理中，搜索和日志分析是两大核心场景。PostgreSQL 作为一款强大的关系型数据库，通过 GIN (Generalized Inverted Index) 索引，也能提供全文检索能力。然而，当面对海量日志数据、复杂的分析需求时，专门的搜索引擎 Easysearch 往往展现出其“专业”的优势。 本文将从底层数据结构出发，对比 Easysearch 和 PostgreSQL GIN 索 … - [Easysearch：中文搜索一定要装分词器吗？](https://easysearch.cn/knowledge-base/usage/easysearch-chinese-search-without-tokenizer/): 在 Easysearch（以及 Elasticsearch）的社区讨论中，这几乎是一个月经贴：“我们要上中文搜索，是不是必须安装 IK 分词器？” 很多新手开发者的第一反应是：“当然！中文没有空格，不装分词器怎么搜？” 但答案其实是：不一定。 甚至在某些特定场景下，不装分词器反而效果更好。 本文将从搜索引擎的底层索引原理出发，探讨在不安装第三方分词插件的情况下，Easysearch 如何处理中文， … - [IOException collecting best scoring results - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/ioexception-collecting-best-scoring-results-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # IOException collecting best scoring results 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起 … - [PropName 不能有空值 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/propname-must-not-have-a-null-value-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8 1. 错误异常的基本描述 # PropName 不能有空值 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Span not 查询必须使用 dist 或 pre 和 post 参数（或不使用）—— 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/span-not-can-either-use-dist-or-pre-post-or-none-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Span not 查询必须使用 dist 或 pre 和 post 参数（或不使用）— 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起 … - [Unexpected trailing characters found - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unexpected-trailing-characters-found-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # Unexpected trailing characters found 表示 Elasticsearch 在解析时间间隔字符串时，发现有效时间间隔后还有额外的未识别字符。 从源码可见，这个异常在时间间隔解析路径中抛出，当解析完成后字符串还有剩余字符时触发。 典型报错 # ParsingException: Invalid … - [Waiting until metadata writes are unblocked - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/waiting-until-metadata-writes-are-unblocked-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.11-8.9 1. 错误异常的基本描述 # Waiting until metadata writes are unblocked 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一 … - [主节点选举等待加入超时配置](https://easysearch.cn/knowledge-base/easysearch_config/discovery.zen.master_election.wait_for_joins_timeout/): 配置项作用 # discovery.zen.master_election.wait_for_joins_timeout 配置项用于控制主节点选举过程中等待其他主节点加入的超时时间。 当一个节点被选举为候选主节点时，它会等待其他具有主节点资格的节点加入集群，此配置决定了等待的最长时间。 配置项属性 # 配置路径: … - [传入的集群状态任期与当前任期不匹配 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/incoming-term-clusterstate-term-does-not-match-current-term-how-to-solve-this-elasticsearch-exception/): 适用版本： 7-7.15 1. 错误异常的基本描述 # 传入的集群状态任期与当前任期不匹配 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [创建快照](https://easysearch.cn/knowledge-base/easysearch_api/create-snapshot/): 在指定的快照仓库中创建快照，备份索引数据。 API 格式 # POST /_snapshot/{repository}/{snapshot} PUT /_snapshot/{repository}/{snapshot} API 作用 # 该 API 用于创建快照备份： 备份一个或多个索引到指定的快照仓库 支持选择性备份（指定索引列表） 可选包含集群全局状态 支持增量快照 API 参数 # … - [字段 fieldName 不支持 ShapeType MULTILINESTRING 查询 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/field-fieldname-does-not-support-shapetype-multilinestring-queries-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.16-8.9 1. 错误异常的基本描述 # 字段 fieldName 不支持 ShapeType MULTILINESTRING 查询 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状 … - [字段名称的未知值 - 可接受的值为 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unknown-value-v-for-field-name-accepted-values-are-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.16-8.6 1. 错误异常的基本描述 # 字段名称的未知值 - 可接受的值为 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [导入悬空索引](https://easysearch.cn/knowledge-base/easysearch_api/import-dangling-index/): 将指定的悬空索引导入回集群，恢复其元数据和可用性。 API 格式 # POST /_dangling/{index_uuid} 注意：API 路径使用 index_uuid 而非 index_name。 API 作用 # 该 API 用于将悬空索引导入回集群。悬空索引是指在磁盘上存在但未在集群状态中注册的索引。该 API 允许管理员恢复这些索引。 API 参数 # 路径参数 # … - [必须是一个数组 - 如何解决这个 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/must-be-an-array-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.3-8.9 1. 错误异常的基本描述 # 必须是一个数组 - 如何解决这个 Elasticsearch 异常 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [快照管理后端角色过滤配置](https://easysearch.cn/knowledge-base/easysearch_config/snapshot_management.filter_by_backend_roles/): 配置项作用 # snapshot_management.filter_by_backend_roles 配置项用于控制是否根据用户的后端角色来过滤快照管理策略。 当设置为 true 时，系统会根据用户的后端角色权限来决定用户是否有权限执行特定的快照管理操作，实现基于角色的访问控制（RBAC）。 配置项属性 # 配置路径: … - [快照线程池配置](https://easysearch.cn/knowledge-base/easysearch_config/thread_pool.snapshot/): 配置项作用 # thread_pool.snapshot 相关配置项控制用于执行快照创建和恢复操作的线程池。快照操作用于备份数据到共享存储或从备份恢复数据。该线程池采用伸缩线程池类型。 配置项类型 # 该配置项为静态配置，需要在启动时设置，修改后需要重启节点才能生效。 默认值 # thread_pool.snapshot.core: 1 thread_pool.snapshot.max: … - [打开索引请求未能得到确认 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/open-index-request-failed-to-be-acknowledged-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.7-8.9 1. 错误异常的基本描述 # 打开索引请求未能得到确认 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [指定的foreach对象不是数组集合 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/specified-foreach-object-was-not-a-an-array-collection-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.3-8.9 1. 错误异常的基本描述 # 指定的foreach对象不是数组集合 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法启动 Transform 任务，因为状态不允许 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-start-task-for-transform-because-state-was-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.5-8.9 1. 错误异常的基本描述 # Cannot start task for transform [xxx], because state was [xxx] 表示 Elasticsearch 在尝试启动一个 Transform 任务时，发现该任务的底层 Indexer 状态不在允许的运行状态集合（RUNNING_STATES）中，因此拒绝执行启动操作。 … - [无法解析 PagerDuty 事件模板，字段解析失败 (Could not parse pager duty event template failed to parse field) - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-pager-duty-event-template-failed-to-parse-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # 无法解析 PagerDuty 事件模板，字段解析失败 (Could not parse pager duty event template failed to parse field) 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入 … - [无法解析 Watch 状态：解析字段失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-watch-status-for-failed-to-parse-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.x 1. 错误异常的基本描述 # could not parse watch status for [<watch_id>]. failed to parse field [<field>] 表示 Elasticsearch 在解析某个 Watch 的状态对象时，进入了指定字段的子解析逻辑，但内部解析失败。 根据日志上下文， … - [期望分析器为字符串但发现了其他类型 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/expecting-the-analyzer-at-to-be-a-string-but-found-instead-how-to-solve-this-elasticsearch-exception/): 适用版本： 7-7.15 1. 错误异常的基本描述 # 期望分析器为字符串但发现了其他类型 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [未注册的聚合 registryKey](https://easysearch.cn/knowledge-base/elasticsearch_error/unregistered-aggregation-registrykey-getname-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.1-8.4 1. 错误异常的基本描述 # 未注册的聚合 registryKey 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [正则表达式规则文件格式错误：期望对象却收到其他内容 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/malformed-regular-expression-file-expecting-object-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # malformed regular expression file; expecting 'object' 是 Elasticsearch 在解析正则表达式规则文件（通常是 YAML 格式）时抛出的解析异常。该错误表示解析器在某个位置期望读取到一个对象（START_OBJECT），但实际读到的却是其他类型的 token（如数组、字符串标 … - [短语前缀查询 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/phrase-prefix-query-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.3-8.9 1. 错误异常的基本描述 # 短语前缀查询 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [类型不匹配：提供了类型 source type 但映射器的类型为 type - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/type-mismatch-provide-type-source-type-but-mapper-is-of-type-type-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.12-7.17 1. 错误异常的基本描述 # 类型不匹配：提供了类型 source type 但映射器的类型为 type 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 … - [缺少 explanation description - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/missing-explanation-description-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.x 1. 错误异常的基本描述 # missing explanation description 出现在 Elasticsearch 解析 Explanation 结构时。Explanation 通常包含 value、description 和可选的 details；保留代码显示，只要 description 为空，就会直接抛出 ParsingException。 常见 … - [节点已关闭 (node_closed_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/node_closed_exception/): 为什么这个错误发生 # node_closed_exception 表示尝试与已关闭的节点通信。节点可能已正常关闭或崩溃。 这个错误可能由以下原因引起： 节点正常关闭：节点被正常关闭 节点崩溃：节点进程因错误崩溃 服务重启：节点服务正在重启 节点离线：节点网络断开 资源耗尽：节点因资源不足而关闭 如何修复这个错误 # 1. 检查节点状态 # # 查看集群中的节点 GET … - [解析 data attachment 时应为指定字段却读到其他 token - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-data-attachment-expected-field-but-found-instead-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # could not parse data attachment. expected [format] field but found [token] instead 是 Elasticsearch 在解析 Watcher 的 data attachment 配置时抛出的解析异常。该错误表示解析器在读取 data attachment … - [解析角色索引权限失败，出现意外字段 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-indices-privileges-for-role-unexpected-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # 解析角色索引权限失败，出现意外字段 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [跟随者元数据同步间隔配置](https://easysearch.cn/knowledge-base/easysearch_config/replication.follower.metadata_sync_interval/): 配置项作用 # replication.follower.metadata_sync_interval 配置项用于控制跟随者节点从 Leader 集群轮询元数据同步的间隔时间。 元数据包括索引的设置（settings）、映射（mappings）和别名（aliases）。此配置决定了 Follower 检查 Leader 元数据变更的频率。 配置项属性 # 配置路径: … - [集群并发重新平衡数量配置](https://easysearch.cn/knowledge-base/easysearch_config/cluster.routing.allocation.cluster_concurrent_rebalance/): 配置项作用 # cluster.routing.allocation.cluster_concurrent_rebalance 配置项控制集群中允许同时进行的重新平衡（rebalance）操作的最大数量。重新平衡是指分片在节点间的迁移操作。此配置用于控制集群重新平衡的并发度，防止过多的同时迁移影响集群性能。 配置项类型 # 该配置项为动态配置，可以在运行时通过集群设置 API 进行修改。 默认 … - [composite 聚合请求的 bucket 数超过上限 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/trying-to-create-too-many-buckets-must-be-less-than-or-equal-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # Trying to create too many buckets. Must be less than or equal to: [bucketLimit] but was [size] 是 Elasticsearch 在执行聚合请求时抛出的异常，表示当前请求试图创建的 bucket 数量超过了集群配置的上限。 与普通的 terms … - [ConvertToScriptException - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/converttoscriptexception-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # ConvertToScriptException 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Easysearch 介绍：面向企业的自主可控搜索引擎详解](https://easysearch.cn/knowledge-base/basic/easysearch-introduction-enterprise-search-engine/): 在当前企业数字化转型的深水区，搜索引擎作为数据智能的底层基石，正面临着**“安全合规”、“成本控制”与“架构演进”**的三重挑战。 尽管通用的开源搜索技术已经普及，但在面对严苛的企业级需求——特别是信创环境适配、数据隐私保护以及海量日志存储成本时，基础开源方案往往显得力不从心，通常需要企业投入大量的二次开发成本或购买昂贵的商业插件。 INFINI Easysearch 是一款专注于企业级场景的分布 … - [Easysearch 规则引擎详解](https://easysearch.cn/knowledge-base/usage/easysearch-rule-engine-guide/): 概述 # Easysearch 规则引擎是一个高性能的文本规则匹配系统，通过 Ingest Pipeline 集成，可以对文档进行实时规则匹配和标签标注。它支持复杂的规则表达式语法，使用 AC 自动机算法实现高效匹配，并支持多节点集群环境下的规则同步。 核心架构 # 规则引擎采用插件化架构，主要组件包括： 规则编译服务：将规则文本编译为高效的数据结构 索引管理服务：管理规则库的元数据和状态 … - [Geohash 必须是字符串 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/geohash-must-be-a-string-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # geohash must be a string 是 Elasticsearch 在处理地理空间数据（geo-point / geo-shape）时抛出的解析异常。当请求体中 geohash 字段的值不是字符串类型时，Elasticsearch 会在解析阶段直接拒绝该请求，并返回 400 Bad Request。 该异常通常出现在以下场 … - [Incoming last accepted version - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/incoming-last-accepted-version-how-to-solve-this-elasticsearch-exception/): 适用版本： 7-7.15 1. 错误异常的基本描述 # Incoming last accepted version 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接 … - [Ingest GeoIP 缓存大小配置](https://easysearch.cn/knowledge-base/easysearch_config/ingest.geoip.cache_size/): 配置项作用 # ingest.geoip.cache_size 配置项控制 Ingest GeoIP 处理器的内存缓存大小。 默认值 # 1000 配置类型 # 静态配置 配置格式 # # 默认配置 ingest.geoip.cache_size: 1000 # 增加缓存大小 ingest.geoip.cache_size: 5000 - [minute 值超出 0-59 范围 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/invalid-time-minute-value-possible-values-may-be-between-0-and-59-incl-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # invalid time minute value [n] (possible values may be between 0 and 59 incl.) 是 Elasticsearch 在解析时间相关配置（如 Watcher 的 trigger.schedule、集群启动时区配置、定时任务等）时抛出的参数校验异常。 … - [Publication currentPublication get already in progress - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/publication-currentpublication-get-already-in-progress-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.16-8.9 1. 错误异常的基本描述 # Publication currentPublication get already in progress 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、 … - [Span within 必须包含 big 子句 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/span-within-must-include-big-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Span within 必须包含 big 子句 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Watcher 加密密钥必须配置在 Keystore 中 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/setting-watcherfield-encryption-key-setting-getkey-must-be-set-in-keystore-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.3-8.9 1. 错误异常的基本描述 # 当 Elasticsearch 的 Watcher 功能启用了加密（encryption）相关配置时，系统会要求在 keystore 中配置加密密钥 xpack.watcher.encryption_key。如果该密钥未正确写入 keystore，节点启动时 Watcher 服务会直接抛出以下异常并阻止正常启动： setting … - [Zen 故障检测配置](https://easysearch.cn/knowledge-base/easysearch_config/discovery.zen.fd/): 配置项概述 # Zen 故障检测（Fault Detection，简称 FD）机制用于监控集群中节点的健康状态。当检测到节点故障时，会触发相应的恢复机制，如重新分配分片或选举新的主节点。 配置项 默认值 说明 discovery.zen.fd.ping_interval 1s Ping 间隔时间 discovery.zen.fd.ping_timeout 30s Ping 超时 … - [不支持的数据库类型](https://easysearch.cn/knowledge-base/elasticsearch_error/unsupported-database-type-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # 不支持的数据库类型 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [创建嵌入向量](https://easysearch.cn/knowledge-base/easysearch_api/create-embedding-vector/): API 状态说明 # 重要提示：POST /_ai/embeddings API 在 Easysearch 中已废弃，调用此 API 会返回 HTTP 410 (Gone) 状态码。 废弃的 API # POST /_ai/embed POST /_ai/embed/{model} 响应状态 # 调用已废弃的端点时会返回： 状态码：410 Gone 错误信 … - [创建搜索管道](https://easysearch.cn/knowledge-base/easysearch_api/create-search-pipeline/): 搜索管道（Search Pipeline）是 Easysearch 中用于自定义搜索请求和响应处理的机制。通过定义一系列处理器（processors），可以在搜索执行前修改请求、在返回结果前处理响应。 API # PUT /_search/pipeline/{id} API 的作用 # 创建新的搜索管道或更新已存在的管道。搜索管道的主要功能包括： 请求处理：在搜索执行前修改搜索请求（查询重 … - [别名请求不被允许 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/alias-requests-are-not-allowed-for-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # Alias requests are not allowed for users who have field or document level security enabled 是 Elasticsearch 安全模块在检测到冲突操作时抛出的异常。当用户同时具备以下两个条件时触发： 该用户在某一个（或多个）索引上启用了字段级安 … - [发送请求传输异常 (send_request_transport_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/send_request_transport_exception/): 为什么这个错误发生 # send_request_transport_exception 表示通过传输层发送请求到远程节点时失败。这是一个传输层异常，通常在节点间通信时发生。 这个错误可能由以下原因引起： 网络连接中断：与远程节点的网络连接中断 远程节点故障：目标节点发生故障或离线 超时：请求发送超时 连接池耗尽：连接池已满无法创建新连接 序列化失败：请求序列化失败 防火墙阻止：防火墙阻止了请 … - [合并分片结果失败 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-merge-shard-results-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.4-8.9 1. 错误异常的基本描述 # Failed to merge shard results 通常出现在 Elasticsearch 执行搜索、聚合或排序请求的归并阶段。请求会先在各个分片上独立执行，协调节点再把每个分片返回的结果做 reduce、排序、聚合合并；如果某个分片返回异常结果、归并过程中触发 IO 问题，或者聚合器在 merge 阶段无法处理分片返回值，就可 … - [同一动态模板中不能同时指定映射和运行时字段 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/mapping-and-runtime-cannot-be-both-specified-in-the-same-dynamic-template-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.11-7.15 1. 错误异常的基本描述 # 同一动态模板中不能同时指定映射和运行时字段 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [同时设置了 endpoint_suffix 和 primary endpoint - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/both-an-endpoint-suffix-as-well-as-a-primary-endpoint-were-set-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.8-8.9 1. 错误异常的基本描述 # Both an endpoint suffix as well as a primary endpoint were set 表示 Elasticsearch 在构造 Azure 存储连接串时，发现你同时配置了 endpoint_suffix 和 primary endpoint。这两种方式都可以决定主服务地址，但语义重叠，因此实现明确 … - [字段数据断路器内存限制配置](https://easysearch.cn/knowledge-base/easysearch_config/indices.breaker.fielddata.limit/): 配置项作用 # indices.breaker.fielddata.limit 配置项控制字段数据断路器的最大内存限制，用于防止加载字段数据时导致 JVM 堆内存溢出。 默认值 # 40%（JVM 堆内存的 40%） 配置类型 # 动态配置 配置格式 # # 默认配置 indices.breaker.fielddata.limit: 40% # … - [意外致命内部错误 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unexpected-fatal-internal-error-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.12-8.6 1. 错误异常的基本描述 # 意外致命内部错误 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法停止汇总作业任务 – 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-stop-task-for-rollup-job-job-getconfig-getid-because-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # 无法停止汇总作业任务 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法关闭索引生命周期服务 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unable-to-close-index-lifecycle-services-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.4-8.9 1. 错误异常的基本描述 # 无法关闭索引生命周期服务 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法执行请求的操作 – 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unable-to-perform-requested-action-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.7-8.9 1. 错误异常的基本描述 # 无法执行请求的操作 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法解析索引的映射 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-parse-the-mapping-for-index-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.11-8.9 1. 错误异常的基本描述 # 无法解析索引的映射 表示 Elasticsearch 在读取某个索引的 mapping 结构时失败了。结合当前页面保留的源码片段，这个异常并不是普通搜索请求解析失败，而是系统在读取索引 mapping 中的元信息时抛出的错误，典型场景包括安全索引、系统索引或升级过程中需要检查 mapping 元数据的内部流程。 常见现象 # 集群 … - [无法验证存储库 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-verify-repository-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.4-8.9 1. 错误异常的基本描述 # failed to verify repository 表示 Elasticsearch 已经识别到某个快照仓库定义，但在执行仓库校验时失败了。仓库校验的目的，是确认参与校验的节点都能访问同一份仓库存储，并且具备正确的读写权限。因此它比“创建仓库成功”更进一步，更能暴露共享文件系统、对象存储访问权限、节点间可见性不一致等问题。 从当前日 … - [时间序列模式下索引ID无效 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/invalid-id-for-index-in-time-series-mode-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # 时间序列模式下索引ID无效 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [时间点初始保持活跃时间配置](https://easysearch.cn/knowledge-base/easysearch_config/point_in_time.init.keep_alive/): 配置项概述 # point_in_time.init.keep_alive 配置项控制时间点（Point In Time，PIT）上下文的初始保持活跃时间。 配置项 默认值 说明 point_in_time.init.keep_alive 30s PIT 初始保持活跃时间 配置说明 # point_in_time.init.keep_alive # 配置项作用： … - [未为设置指定有效的主机端口对 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/no-valid-host-port-pairs-specified-for-setting-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-6.8 1. 错误异常的基本描述 # 未为设置指定有效的主机端口对 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [未找到要冻结或解冻的索引 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/no-index-found-to-request-freeze-freeze-unfreeze-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 未找到要冻结或解冻的索引 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [汇总任务在完成前停止 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/rollup-stopped-before-completion-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.11-7.11 1. 错误异常的基本描述 # 汇总任务在完成前停止 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [没有认证用户 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/there-is-no-authenticated-user-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 没有认证用户 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返回 400、404、409、429、500 … - [索引或数据流与别名同名 – 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/an-index-or-data-stream-exists-with-the-same-name-as-the-alias-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.14-8.9 1. 错误异常的基本描述 # an index or data stream exists with the same name as the alias 是 Elasticsearch 在**创建或更新别名（Alias）**时抛出的 InvalidAliasNameException 异常。该错误的核心含义是：你试图使用的别名名称，已经被一个索引或数据流占用了。 … - [经度必须是数字 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/longitude-must-be-a-number-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 经度必须是数字 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [集群发现配置: cluster_formation_warning_timeout](https://easysearch.cn/knowledge-base/easysearch_config/discovery.cluster_formation_warning_timeout/): discovery.cluster_formation_warning_timeout 配置项控制集群发现相关行为。 配置格式 # # 默认配置 discovery.cluster_formation_warning_timeout: default - [All Failed to update cluster state during repository operation – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/all-failed-to-update-cluster-state-during-repository-operation-how-to-solve-this-elasticsearch-exception/): title: “Failed to update cluster state during repository operation - 如何解决此 Elasticsearch 异常” date: “2026-03-02T08:00:00+08:00” blogAuthor: “INFINI Labs” category: … - [All String join – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/all-string-join-how-to-solve-this-elasticsearch-exception/): 适用版本： 5.x-6.x（涉及 Type 体系的版本） 1. 错误异常的基本描述 # All String join 并非一个标准的 Elasticsearch 错误名称，而是社区对一类特定异常的概括性描述。该异常通常出现在 Elasticsearch 5.x 至 6.x 版本中，当客户端请求引用了不存在的类型（Type）时，服务端会抛出 TypeMissingException，并在异常构 … - [Allocation命令格式错误——完成解析命令时如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/allocation-command-is-malformed-done-parsing-a-command-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # Allocation命令格式错误——完成解析命令时如何解决此Elasticsearch异常 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索 … - [API密钥缓存清理失败，请手动清理缓存——如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/clearing-the-api-key-cache-failed-please-clear-the-caches-manually-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.16-8.9 1. 错误异常的基本描述 # API密钥缓存清理失败，请手动清理缓存— 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Easysearch 搜索查询是如何被处理的？一文讲懂搜索引擎内部机制](https://easysearch.cn/knowledge-base/basic/easysearch-search-query-processing-explained/): 当我们在搜索框中输入“Easysearch 快速入门”，然后按下回车，零点几秒后，相关的文档列表便呈现在眼前。这个过程看似简单，但背后却是一套精密、高效的分布式协作系统在运转。 它不是简单地遍历每一篇文档去寻找关键词。相反，它像一位经验丰富的图书管理员，能瞬间从亿万册藏书中，不仅找到相关的书籍，还能按照与你需求的匹配度排好序。 今天，我们就将跟随一个搜索请求，开启一场深入 Easysearch 内 … - [HTTP 发布地址配置](https://easysearch.cn/knowledge-base/easysearch_config/http.publish_host/): 配置项作用 # http.publish_host 配置项指定向客户端发布的 HTTP 服务主机地址，用于告诉客户端如何连接回服务器。 是否可选 # 是 默认值 # [] (空列表，依次回退到 http.bind_host、http.host、network.publish_host、network.host) 配置项类型 # 静态配置 - 需要重启节点才能生效 配置格式 # # 发布主 … - [No default Azure data store configured - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/no-default-azure-data-store-configured-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-6.8 1. 错误异常的基本描述 # No default Azure data store configured 出现在 Azure 仓库客户端配置选择默认存储账户时。源码会遍历所有 Azure storage settings，如果找不到任何 isActiveByDefault() 为真的配置，就抛出这条 SettingsException。 常见现象 # 注册或初 … - [Snapshot 线程池核心大小配置](https://easysearch.cn/knowledge-base/easysearch_config/thread_pool.snapshot.core/): 配置项作用 # thread_pool.snapshot.core 配置项用于控制快照线程池的核心线程数。 Snapshot 线程池用于处理所有与快照相关的操作，包括创建快照、恢复快照、删除快照等。 配置项属性 # 配置路径: thread_pool.snapshot.core 数据类型: Integer（整数） 默认值: 1 是否可选: 是 作用域: NodeScope（节点级别） 动态更 … - [Transport TCP 压缩配置](https://easysearch.cn/knowledge-base/easysearch_config/transport.tcp.compress/): 配置项作用 # transport.tcp.compress 配置项用于控制是否启用 TCP 传输中的压缩功能。 配置项属性 # 配置路径: transport.tcp.compress 数据类型: Boolean（布尔值） 默认值: false 是否可选: 是 作用域: NodeScope（节点级别） 动态更新: 否（需要重启节点生效） 废弃状态: 已废弃， … - [Unexpected null response from test query - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unexpected-null-response-from-test-query-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.4-7.13 1. 错误异常的基本描述 # Unexpected null response from test query 表示 Elasticsearch Transform 在执行测试查询验证时，收到了空的搜索响应。 从源码可见，这个异常在 Transform 配置验证路径中抛出，当测试查询返回 null 时触发。 典型报错 # … - [Unicode sequence should use [2-8] hex digits - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unicode-sequence-should-use-2-8-hex-digits-has-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.13-7.15 1. 错误异常的基本描述 # Unicode sequence should use [2-8] hex digits 表示 Elasticsearch 在解析 SQL 查询中的 Unicode 转义序列时，发现十六进制数字位数不在 2-8 范围内。 从源码可见，这个异常在 SQL 字符串解析路径中抛出，当 Unicode 序列 \u{...} 中的十六进制位数 … - [Watch reporting Aborting due to maximum number of retries hit - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/watch-reporting-aborting-due-to-maximum-number-of-retries-hit-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # Watch reporting Aborting due to maximum number of retries hit 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还 … - [Wildcard query - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/wildcard-query-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.3-8.9 1. 错误异常的基本描述 # Wildcard query 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [仓库未处于启动状态 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/repository-is-not-in-started-state-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # repository is not in started state 表示 Elasticsearch 当前拿到的 repository 实例还没有进入可正常服务的 started 状态，却已经被用于加载仓库数据、验证仓库、执行快照或恢复等操作。根据当前源码片段，这类异常来自 notStartedException()，说明系统在仓库初 … - [关闭索引请求未能得到确认 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/close-index-request-failed-to-be-acknowledged-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.7-8.9 1. 错误异常的基本描述 # 关闭索引请求未能得到确认 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [写入慢、查询慢，Easysearch 如何快速定位瓶颈](https://easysearch.cn/knowledge-base/usage/easysearch-slow-write-slow-query-bottleneck-diagnosis/): 性能问题往往是“幽灵”般的存在：有时是写入吞吐上不去，有时是查询延迟忽高忽低。对于 Easysearch 而言，性能瓶颈通常隐藏在 I/O 瓶颈、GC 停顿、线程池积压或烂查询这四大角落。本文将提供一套标准化的排查思路，教你利用 _nodes/stats、Profile API 和 Slow Log 快速揪出幕后真凶。 “为什么我的 Easysearch 写入速度只有几千条/秒？” “为什么这 … - [创建 Point-in-time](https://easysearch.cn/knowledge-base/easysearch_api/create-point-in-time/): Point In Time (PIT) 是 Easysearch 中的一种搜索机制，允许在特定时间点上的数据集上进行搜索，而不是在实时数据集上搜索。PIT 是实现深度分页（deep pagination）的推荐方式。 API # POST /{index}/_pit API 的作用 # 创建 PIT 上下文，用于在冻结的数据集上进行搜索。PIT 的主要功能包括： 数据快照：锁定索引在特定时间 … - [单播发现并发连接数配置](https://easysearch.cn/knowledge-base/easysearch_config/discovery.zen.ping.unicast.concurrent_connects/): 配置项作用 # discovery.zen.ping.unicast.concurrent_connects 配置项用于控制种子主机解析时的最大并发连接数。 当节点解析配置的种子主机列表时，此配置决定了同时可以发起多少个并发连接。 配置项属性 # 配置路径: discovery.zen.ping.unicast.concurrent_connects 数据类型: integer 默认值: … - [字段值缺失 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/missing-value-for-field-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 字段值缺失 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [对象映射名称的 subobjects 参数无法更新 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/the-subobjects-parameter-can-t-be-updated-for-the-object-mapping-name-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.3-8.9 1. 错误异常的基本描述 # 对象映射名称的 subobjects 参数无法更新 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返 … - [无法在只读仓库上执行清理操作 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-run-cleanup-on-readonly-repository-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.4-8.9 1. 错误异常的基本描述 # cannot run cleanup on readonly repository 表示你正在尝试对一个只读快照仓库执行 cleanup 操作。cleanup 并不是只读查询，它会扫描并移除仓库中不再被引用的遗留 blob，因此本质上属于写操作或至少是需要修改仓库内容的维护动作。对于只读仓库，Elasticsearch 会直接拒绝这类请 … - [无法对直方图进行取整 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/can-t-round-a-histogram-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.9-8.9 1. 错误异常的基本描述 # can't round a [histogram] 是 Elasticsearch 在执行聚合（Aggregation）时抛出的异常，完整的英文报错通常为： AggregationExecutionException: can't round a [histogram] 该异常表示：某个聚合操作（如 date_histogram … - [无法解析消息附件字段，字段期望布尔值（Could not parse message attachment field. expected a boolean value for [...] field）- 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-message-attachment-field-expected-a-boolean-value-for-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.x 1. 错误异常的基本描述 # could not parse message attachment field. expected a boolean value for [...] field; but found [...] 表示某个 message attachment 字段应为布尔值，但实际给了错误 token。 从保留源码看，典型字段是 short。 2. … - [无法解析监视器执行请求，出现未预期的布尔字段（Could not parse watch execution request. unexpected boolean field）- 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-watch-execution-request-unexpected-boolean-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.x 1. 错误异常的基本描述 # could not parse watch execution request. unexpected boolean field [...] 表示 Execute Watch 请求体中出现了一个布尔值字段，但这个字段名不在解析器允许的范围内。 从源码可见，布尔值分支只接受非常有限的几个字段，例如 ignore_condition … - [无法配置 Azure compute service - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unable-to-configure-azure-compute-service-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Unable to configure Azure compute service 表示 Elasticsearch 在初始化 Azure Compute Management 客户端时触发了 IOException，导致无法完成 Azure 相关服务的配置。该异常通常出现在使用 Azure 发现插件（azure-discovery） … - [查询线程池](https://easysearch.cn/knowledge-base/easysearch_api/get-thread-pool/): 此 API 用于显示集群中所有节点的线程池统计信息。 API # GET /_cat/thread_pool GET /_cat/thread_pool/{thread_pool_patterns} API 的作用 # 返回集群中所有节点的线程池详细统计信息，包括： 活跃线程数：当前正在执行的线程数量 线程池大小：线程池的配置大小 队列状态：队列中的任务数和队列容量 拒绝统计：被拒绝的任务数 … - [没有已知的训练模型具有该模型ID - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/no-known-trained-model-with-model-id-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.6-8.9 1. 错误异常的基本描述 # 没有已知的训练模型具有该模型ID 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [没有本地集群状态 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/have-no-local-cluster-state-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 没有本地集群状态 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [端口绑定失败 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-bind-to-port-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.6 1. 错误异常的基本描述 # Failed to bind to [port] 通常发生在 Elasticsearch 节点启动阶段，表示进程尝试监听某个 HTTP 或 transport 端口时失败了。它和 connect_exception 不同，connect_exception 是别人连不上你；而 failed to bind to port 是你自己连“监 … - [索引不存在 (index_not_found_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/index_not_found_exception/): 为什么这个错误发生 # index_not_found_exception 表示尝试访问一个不存在的索引。 这个错误可能由以下原因引起： 索引名称拼写错误：请求中的索引名称输入错误 索引尚未创建：尝试访问还未创建的索引 索引被删除：索引已被删除但客户端仍在尝试访问 大小写不匹配：索引名称区分大小写，请求的大小写与实际不符 集群/别名问题：通过别名访问时，别名不存在或指向不存在的索引 跨集群搜索 … - [网络层请求断路器开销因子配置](https://easysearch.cn/knowledge-base/easysearch_config/network.breaker.inflight_requests.overhead/): 配置项作用 # network.breaker.inflight_requests.overhead 配置项用于控制网络层飞行请求断路器的内存开销乘数（overhead constant）。 此配置是一个放大因子，用于在估算网络请求内存使用时考虑 JVM 内部结构、对象头、网络缓冲区等额外开销，确保内存估算的保守性和安全性。 配置项属性 # 配置路径: … - [获取文档ID失败 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-fetch-doc-id-docid-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.9 1. 错误异常的基本描述 # 获取文档ID失败 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [2026 年中国搜索型数据库市场现状与机遇](https://easysearch.cn/knowledge-base/insight/china-search-database-market-status-and-opportunities-2026/): 2026 年中国搜索型数据库市场现状与机遇 —— 面向 CTO / CIO 的行业研究报告（节选版） 一、报告摘要（Executive Summary） # 进入 2026 年，搜索型数据库已成为中国企业数字基础设施中的关键组成部分，广泛应用于日志分析、业务搜索、数据治理、安全审计、智能检索及 AI 应用支撑等核心场景。随着数据规模持续扩大、业务实时性要求不断提升，以及国家对信息技术自主可控要求 … - [aggregation m.getName() is of non-supported type - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/aggregation-m-getname-is-of-non-supported-type-m-gettype-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9+ 1. 错误异常的基本描述 # Aggregation [" + m.getName() + "] is of non-supported type [" + m.getType() + "] 是 Elasticsearch 在执行**聚合（aggregation）**时抛出的类型不兼容错误。当你在某个字段上执行聚合操作，但该 … - [cannot find an aggregation named aggname in - 聚合路径中找不到指定名称的聚合如何解决](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-find-an-aggregation-named-aggname-in-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # Cannot find an aggregation named [aggName] in [containingAggName] 表示在 Elasticsearch 聚合查询中，你在聚合属性路径、buckets_path 或脚本访问路径里引用了一个不存在的聚合名称。Elasticsearch 在当前容器聚合里查找 aggName 时 … - [has_privileges 请求中不支持的字段 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/field-is-not-supported-in-a-has-privileges-request-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Field [xxx] is not supported in a has_privileges request 是 Elasticsearch 安全模块在解析 has_privileges API 请求时抛出的异常。该 API 用于检查当前用户是否拥有指定的集群权限或索引权限，其请求体结构有严格的字段限制。一旦请求中包含该接口不支持的 … - [HTTP TCP Keep-Alive 探测间隔配置](https://easysearch.cn/knowledge-base/easysearch_config/http.tcp.keep_interval/): 配置项作用 # http.tcp.keep_interval 配置项用于控制TCP Keep-Alive 探测包之间的发送间隔时间。 当连接空闲超过 keep_idle 时间后，Keep-Alive 机制开始发送探测包。如果探测包未收到响应，系统会按照此配置指定的时间间隔继续发送后续的探测包。 配置项属性 # 配置路径: http.tcp.keep_interval 数据类型: … - [Significant terms 聚合无法应用于字段 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/significant-terms-aggregation-cannot-be-applied-to-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.7 1. 错误异常的基本描述 # Significant terms 聚合无法应用于字段 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可 … - [Span near 子句必须是 span query 类型 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/span-near-clauses-must-be-of-type-span-query-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Span near 子句必须是 span query 类型 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接 … - [Span not 必须包含 include span 查询子句 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/span-not-must-have-include-span-query-clause-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Span not 必须包含 include span 查询子句 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Span not 查询不支持 currentFieldName – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/span-not-query-does-not-support-currentfieldname-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Span not 查询不支持 currentFieldName 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [URL不包含协议方案——如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/url-does-not-contain-a-scheme-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # URL不包含协议方案— 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [一条查询搜多个字段，Easysearch 是怎么做的](https://easysearch.cn/knowledge-base/usage/one-query-multiple-fields-how-easysearch-does-it/): 一、核心基础：multi_match 查询的底层逻辑 # multi_match 是 Easysearch 实现多字段查询的核心语法，其本质是串行遍历所有指定字段，为每个字段构建独立子查询，再通过 DisjunctionMaxQuery（Lucene 核心查询类型）聚合子查询结果并排序。这种设计既简化了查询构造，又保证了结果相关性，核心价值体现在三个方面： 简化查询构造：无需手动通过 bool … - [不存在 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/does-not-exist-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.3-7.15 1. 错误异常的基本描述 # 不存在 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返回 400、404、409、429、500 … - [从写入到查询：一条数据在 Easysearch 中的奇幻漂流](https://easysearch.cn/knowledge-base/basic/from-write-to-query-data-journey-in-easysearch/): 当我们调用 Easysearch 的 API 写入一条数据，并在几毫秒后将其搜索出来时，一切看起来都那么自然且顺滑。但在那短暂的眨眼之间，这条数据其实刚刚经历了一场惊心动魄的“奇幻漂流”。 它是如何被安全存储的？为什么有时候刚写进去却搜不到？搜索时它是如何被瞬间定位的？ 今天，我们不谈枯燥的代码，而是化身为一条 JSON 数据，亲自走一遍 Easysearch 的内部旅程。 第一站：登陆与安检（协 … - [即使达到最大子节点数仍然缺少通配符子节点 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/missing-wild-card-child-even-though-maximum-children-reached-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.16-8.2 1. 错误异常的基本描述 # 即使达到最大子节点数仍然缺少通配符子节点 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [发现多个具有相同发行者的OpenID Connect领域 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/found-multiple-openid-connect-realm-with-issuer-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.2-8.9 1. 错误异常的基本描述 # 发现多个具有相同发行者的OpenID Connect领域 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能 … - [快照分片信息并发获取配置](https://easysearch.cn/knowledge-base/easysearch_config/cluster.snapshot.info.max_concurrent_fetches/): 配置项作用 # cluster.snapshot.info.max_concurrent_fetches 配置项用于控制从快照仓库并发获取分片大小信息的最大请求数量。 在快照恢复过程中，节点需要获取快照中每个分片的大小信息，此配置控制同时进行多少个并发获取请求。 配置项属性 # 配置路径: cluster.snapshot.info.max_concurrent_fetches 数据类型: … - [执行失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-execution-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 执行失败 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返回 400、404、409、429、500 … - [批量操作](https://easysearch.cn/knowledge-base/easysearch_api/bulk-operation/): 在单个请求中执行多个文档操作（索引、创建、更新、删除），减少网络往返次数。 API # POST /_bulk PUT /_bulk POST /{index}/_bulk PUT /{index}/_bulk API 的作用 # Bulk API 允许在单个请求中执行多个文档操作，显著提高批量数据处理的效率。 支持的操作类型 # 操作 描述 index 索引文档，如果存在则覆 … - [搜索归约阶段异常 (reduce_search_phase_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/reduce_search_phase_exception/): 为什么这个错误发生 # reduce_search_phase_exception 表示搜索的归约阶段失败，该阶段合并来自多个分片的结果。 如何修复 # 1. 检查分片状态 # GET /_cat/shards?v 2. 简化聚合 # 减少聚合复杂度。 3. 增加超时时间 # GET /<index>/_search?timeout=30s 预防措施 # 优化聚合查询 监 … - [无法将字段对象解析为地址：未知地址 (Could not parse field object as address unknown address) - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-field-object-as-address-unknown-address-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # 无法将字段对象解析为地址：未知地址 (Could not parse field object as address unknown address) 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性， … - [无法索引到临时汇总索引 tmpIndexName - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unable-to-index-into-temp-rollup-index-tmpindexname-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.12-8.2 1. 错误异常的基本描述 # 无法索引到临时汇总索引 tmpIndexName 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法解析 Watch 状态无效，操作状态缺失 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-watch-watch-status-in-invalid-state-action-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.x 1. 错误异常的基本描述 # could not parse watch [<id>]. watch status in invalid state. action [<action_id>] status is missing 表示 Elasticsearch 在解析 Watch 的 status 时发现：Watch … - [模板名称必须设置映射或运行时字段 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/template-name-must-have-either-mapping-or-runtime-set-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.11-8.9 1. 错误异常的基本描述 # 模板名称必须设置映射或运行时字段 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [没有损坏文件标记 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/there-is-no-corruption-file-marker-how-to-solve-this-elasticsearch-exception/): 适用版本： 7-7.2 1. 错误异常的基本描述 # 没有损坏文件标记 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [百分比应在0-100之间，得到——如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/percentage-should-be-in-0-100-got-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 百分比应在0-100之间，得到— 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [索引压力内存限制配置](https://easysearch.cn/knowledge-base/easysearch_config/indexing_pressure.memory.limit/): 配置项概述 # indexing_pressure.memory.limit 配置控制索引操作可以使用的最大内存量。当内存使用超过限制时，系统会拒绝新的索引请求以防止节点因内存不足而变得不稳定。 配置项 默认值 说明 indexing_pressure.memory.limit 10% 索引操作内存限制 配置说明 # … - [索引存储文件系统锁配置](https://easysearch.cn/knowledge-base/easysearch_config/config_index.store.fs.fs_lock/): 配置项作用 # index.store.fs.fs_lock 配置项控制索引存储层使用的文件系统锁实现类型。 默认值 # native 配置类型 # 索引级配置 取值范围 # native：使用原生文件系统锁 simple：使用简单文件锁 配置格式 # # 默认配置 index.store.fs.fs_lock: native # … - [索引的策略策略 getName 尝试从步骤移动失败 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/policy-policy-for-index-index-getname-failed-trying-to-move-from-step-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # 索引的策略策略 getName 尝试从步骤移动失败 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能 … - [聚合名称不支持正则表达式样式 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/aggregation-name-cannot-support-regular-expression-style-how-to-solve-this-elasticsearch-exception/): 适用版本： 5.x – 8.x 1. 错误异常的基本描述 # Aggregation [aggregation_name] cannot support regular expression style include/exclude settings as they can only be applied to string fields 是 Elasticsearch 在执行 terms … - [获取集群统计信息](https://easysearch.cn/knowledge-base/easysearch_api/get-cluster-stats/): 获取集群级别的统计信息，提供集群的高级别概览，包括节点信息、索引信息和集群健康状态。 API # GET /_cluster/stats GET /_cluster/stats/nodes/{nodeId} API 的作用 # 该 API 用于获取集群级别的统计信息，提供集群的高级别概览。返回的信息包括： 统计类别 描述 节点统计 节点数量、节点角色、 … - [解析 http request 时出现未预期 token - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-http-request-unexpected-token-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # could not parse http request. unexpected token [token] 是 Elasticsearch Watcher 组件在解析 HTTP request 定义时抛出的异常。当 Watcher 的 JSON 解析器在遍历请求定义的过程中，读到了当前位置不应该出现的 token 类型时，就会触发此错 … - [解析坐标维度数量不匹配异常 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/exception-parsing-coordinates-number-of-dimensions-do-not-match-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 解析坐标维度数量不匹配异常 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [设置已配置但其他必要设置未配置 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/setting-is-set-but-and-are-not-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # 设置已配置但其他必要设置未配置 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [跨集群复制跟随者元数据同步间隔配置](https://easysearch.cn/knowledge-base/easysearch_config/plugins.replication.follower.metadata_sync_interval/): 配置项作用 # plugins.replication.follower.metadata_sync_interval 配置项用于控制跟随者节点与领导者节点同步元数据的频率。 配置项属性 # 配置路径: plugins.replication.follower.metadata_sync_interval 数据类型: TimeValue（时间值） 默认值: 60s（60秒） 是否可选: 是 … - [assignment does not exist - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/assignment-does-not-exist-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.17-8.9（机器学习功能） 1. 错误异常的基本描述 # assignment does not exist 是 Elasticsearch 机器学习（Machine Learning）模块中特有的异常，完整报错通常为 ResourceNotFoundException: [deploymentId] assignment does not exist。该异常表示系统尝试对一 … - [could not parse pagerduty event response unexpected field - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-pagerduty-event-response-unexpected-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # could not parse pagerduty event response. unexpected field [field] 是 Elasticsearch Watcher 在与 PagerDuty 集成时抛出的解析异常。当 Watcher 的 PagerDuty action 收到 PagerDuty API 的响应后，如果响 … - [dynamic attachments 出现未预期字段 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-dynamic-attachments-unexpected-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # could not parse dynamic attachments. unexpected field [field] 表示 Elasticsearch 在解析 dynamic attachments 配置时，遇到了当前实现不认识的字段名，因此立即中止解析。 dynamic attachments 是 Elasticsearch 中 … - [Easysearch 聚合分析入门：从指标到桶的核心概念](https://easysearch.cn/knowledge-base/basic/easysearch-aggregation-analysis-metrics-buckets/): 聚合分析（Aggregation）是搜索引擎中非常重要的一类功能，它用于对大量数据进行统计与分类计算，让数据分析变得更直观、更高效。在 Easysearch 中，聚合分析直接支持在搜索请求中对数据执行统计、分组、分桶等操作，是构建分析平台、报表系统以及仪表盘等产品的基础。 本文将围绕 Easysearch 中聚合分析的两个核心概念 —— 指标聚合（Metrics） 与 桶聚合（Buckets），讲 … - [Easysearch：模糊、前缀、通配符查询，什么时候该用，什么时候该禁](https://easysearch.cn/knowledge-base/usage/easysearch-fuzzy-prefix-wildcard-query-when-to-use-when-to-disable/): 一、查询类型总览 # Easysearch 作为 Elasticsearch 国产化替代方案，兼容其核心查询语法，三种模糊匹配查询的核心差异如下： 查询类型 核心能力 性能等级 风险程度 Prefix（前缀） 左匹配检索，利用倒排索引有序性 ⭐⭐⭐⭐⭐ 低 Wildcard（通配符） 支持 ?（单字符）/*（任意字符）匹配 ⭐⭐ 高 Fuzzy（模糊） 容忍拼写错误（基于编 … - [failed to load settings from [source] - 从内联源码加载设置失败](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-load-settings-from-source-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Failed to load settings from [source] 对应的是字符串配置加载路径。源码直接用 XContentFactory.xContent(xContentType).createParser(..., source) 创建解析器，再调用 fromXContent 生成 Settings；任何异常都会被包装为当 … - [failed to load started shards - 已启动分片信息加载失败](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-load-started-shards-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # failed to load started shards 出现在节点 gateway 读取本地分片状态的流程里。源码在返回 NodeGatewayStartedShards 前捕获通用异常并抛出当前错误，因此问题通常与节点本地 shard state 文件、分片目录或恢复状态有关，而不是普通网络请求失败。 这不是"分片还没启 … - [http response header 列表里出现非值 token - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-http-response-expected-a-header-value-for-header-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # could not parse http response. expected a header value for header [name] but found [token] instead 是 Elasticsearch 在解析 HTTP 响应头（HTTP Response Header）时抛出的解析异常。 … - [HTTP 压缩级别配置](https://easysearch.cn/knowledge-base/easysearch_config/http.compression_level/): 配置项作用 # http.compression_level 配置项控制 HTTP 响应压缩的压缩级别。级别 3 是在网络流量和延迟之间的最佳平衡点。 默认值 # 3 配置类型 # 静态配置 取值范围 # 0 ~ 9（压缩级别） 配置格式 # # 默认配置 http.compression_level: 3 # 更高压缩率（更高 CPU 使用） … - [Ingest 处理器异常 (ingest_processor_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/ingest_processor_exception/): 为什么这个错误发生 # ingest_processor_exception 表示在执行 Ingest 管道中的处理器时发生错误。Ingest 管道用于在索引数据前对其进行预处理。 这个错误可能由以下原因引起： 脚本错误：Painless 脚本执行失败 处理器配置错误：处理器配置参数不正确 字段不存在：脚本引用了不存在的字段 类型转换错误：数据类型转换失败 内存不足：处理器消耗过多内存 处理器 … - [Na query malformed must start with start object – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/na-query-malformed-must-start-with-start-object-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Na query malformed must start with start object 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引 … - [No node meta data at – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/no-node-meta-data-at-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # No node meta data at 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [suggest 请求缺少 suggestion 对象 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/missing-suggestion-object-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # missing suggestion object 是 Elasticsearch 在执行 suggest 请求时抛出的解析异常。当 Elasticsearch 解析 suggest 请求体时，如果在 suggest 字段下没有找到任何可识别的 SuggestionBuilder 对象，就会抛出此异常。 常见现象 # … - [Unexpected parameter - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unexpected-parameter-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Unexpected parameter 是 Elasticsearch SQL 模块在解析函数调用时抛出的 ParsingException 异常。当 SQL 语句中调用某个函数时，传入了该函数签名中未定义的参数（无论是位置参数数量不对，还是命名参数名称不在允许列表中），解析器就会抛出此异常并终止当前查询的执行。 该异常属于查询解析阶 … - [不支持的字段 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unsupported-field-parametername-how-to-solve-this-elasticsearch-exception/): 适用版本： 8-8.9 1. 错误异常的基本描述 # 不支持的字段 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返回 400、404、409、429、500 … - [不能包含以下字符 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/must-not-contain-the-following-characters-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.14-8.9 1. 错误异常的基本描述 # 不能包含以下字符 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [临时索引不应触发分片创建 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/temp-index-should-not-trigger-shard-creation-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.8-8.9 1. 错误异常的基本描述 # 临时索引不应触发分片创建 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [内存断路器类型配置](https://easysearch.cn/knowledge-base/easysearch_config/indices.breaker.type/): 配置项作用 # indices.breaker.type 配置项用于控制Easysearch 内存断路器的实现类型。 断路器是 Easysearch 重要的内存保护机制，用于防止内存使用超过限制导致系统崩溃。 配置项属性 # 配置路径: indices.breaker.type 数据类型: String（字符串） 默认值: hierarchy 有效值: hierarchy, none 是否可 … - [参数 radius 不支持该类型 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/parameter-radius-is-not-supported-for-type-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.2-8.9 1. 错误异常的基本描述 # 参数 radius 不支持该类型 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [字段 currentPath 必须是一个对象 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/field-currentpath-must-be-an-object-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.13-7.15 1. 错误异常的基本描述 # 字段 currentPath 必须是一个对象 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [字段类型解析失败 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-field-of-type-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.7 1. 错误异常的基本描述 # 字段类型解析失败 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [当前许可证不符合要求 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/current-license-is-non-compliant-for-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # 当前许可证不符合要求 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [必须是一个字符串 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/must-be-a-string-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.3-8.9 1. 错误异常的基本描述 # 必须是一个字符串 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [握手失败意外的远程集群名称 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/handshake-failed-unexpected-remote-cluster-name-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.6-8.9 1. 错误异常的基本描述 # 握手失败意外的远程集群名称 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [最大并发 PIT 上下文数配置](https://easysearch.cn/knowledge-base/easysearch_config/search.max_open_pit_context/): 配置项作用 # search.max_open_pit_context 配置项控制允许同时打开的 Point In Time (PIT) 上下文的最大数量。PIT 上下文用于查询历史数据状态，此配置限制并发 PIT 上下文数量以防止资源耗尽。 配置项类型 # 该配置项为动态配置，可以在运行时通过集群设置 API 进行修改。 默认值 # 300 是否必需 # 可选配置项（有默认值） … - [未知的条件](https://easysearch.cn/knowledge-base/elasticsearch_error/unknown-condition-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.8-8.9 1. 错误异常的基本描述 # 未知的条件 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [查询API密钥](https://easysearch.cn/knowledge-base/easysearch_api/query-api-key/): 注意：GET /_security/api_key API 在当前版本的 Easysearch 中尚未实现服务器端。 API 说明 # GET /_security/api_key 端点在当前 Easysearch 版本中未实现服务器端 REST 处理器。 虽然客户端库中存在相关的数据结构类（如 GetApiKeyResponse.java 和 ApiKey.java）， … - [磁盘低水位线配置](https://easysearch.cn/knowledge-base/easysearch_config/cluster.routing.allocation.disk.watermark.low/): 配置项作用 # cluster.routing.allocation.disk.watermark.low 配置项用于设置磁盘使用率的低水位线。 当一个节点的磁盘使用率超过此阈值时： 不允许在该节点上分配新的分片 已存在的分片可以继续保留在节点上 这是防止磁盘空间不足的第一道防线，在达到高水位线之前就开始保护系统。 配置项属性 # 配置路径: … - [端口绑定失败 getPortRangeString - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-bind-to-port-getportrangestring-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.6 1. 错误异常的基本描述 # 端口绑定失败 getPortRangeString 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [等待任务完成超时 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/timed-out-waiting-for-completion-of-task-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.7-8.8 1. 错误异常的基本描述 # 等待任务完成超时 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [类型不能为空字符串 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/type-cannot-be-an-empty-string-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.6-8.9 1. 错误异常的基本描述 # 类型不能为空字符串 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [获取字段能力](https://easysearch.cn/knowledge-base/easysearch_api/get-field-caps/): 检索一个或多个索引中指定字段的能力（映射和元数据）信息，包括字段类型、是否可搜索、是否可聚合等。 API 格式 # GET /_field_caps POST /_field_caps GET /{index}/_field_caps POST /{index}/_field_caps API 作用 # 该 API 用于获取指定字段在索引中的能力信息，包括： 字段类 … - [默认允许部分结果配置](https://easysearch.cn/knowledge-base/easysearch_config/search.default_allow_partial_results/): 配置项作用 # search.default_allow_partial_results 配置项控制在搜索请求中未指定 allow_partial_results 参数时的默认行为。当查询涉及多个分片时，如果某些分片失败，此配置决定是返回部分结果还是整个查询失败。 配置项类型 # 该配置项为动态配置，可以在运行时通过集群设置 API 进行修改。 默认值 # true（允许部分结果） … - [Easysearch 安全可控架构详解：权限控制、加密保护、合规日志审计](https://easysearch.cn/knowledge-base/basic/easysearch-security-architecture-guide/): 在企业数字化转型的深水区，数据已成为核心资产。对于承载海量业务数据的分布式搜索引擎而言，“快"是基础要求，而"稳"与"安"则是生存的底线。 特别是在金融、政务、运营商等关键基础设施领域，随着《数据安全法》的实施和信创国产化的推进，搜索引擎不仅需要具备高性能的检索能力，更必须拥有自主可控的安全架构。 INFINI Easysearch 作 … - [Easysearch 文档操作：数据的增删改查](https://easysearch.cn/knowledge-base/usage/easysearch-document-operations-crud/): 在掌握了环境搭建之后，下一步就是学会如何与 INFINI Easysearch 进行“对话”。 作为一款基于 JSON 的分布式搜索引擎，Easysearch 的交互方式非常直观：使用 HTTP 动词（GET, PUT, POST, DELETE）来操作 JSON 文档。这与现代 Web 开发中的 RESTful API 风格完全一致。 本文将带你通过 Dev Tools 或 Curl 完成最核心 … - [Fetch Shard Started 线程池核心大小配置](https://easysearch.cn/knowledge-base/easysearch_config/thread_pool.fetch_shard_started.core/): 配置项作用 # thread_pool.fetch_shard_started.core 配置项用于控制分片启动状态获取线程池的核心线程数。 此线程池负责在集群重启或节点故障恢复时，异步获取各个节点的分片启动状态信息，是集群恢复过程中的关键组件。 配置项属性 # 配置路径: thread_pool.fetch_shard_started.core 数据类型: Integer（整数） 默认值: … - [GCS 代理主机无法解析 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/gcs-proxy-host-is-unknown-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.0-8.9 1. 错误异常的基本描述 # GCS proxy host is unknown 表示 Elasticsearch 在初始化 Google Cloud Storage（GCS）客户端代理时，调用 DNS 解析代理主机名失败，从而抛出 SettingsException。该错误发生在代理对象创建阶段，而非实际发出 HTTP 请求之后，因此一旦出现，GCS 仓库或快照功 … - [geo_polygon 出现非法 token 类型 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/geo-polygon-unexpected-token-type-token-name-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.x 1. 错误异常的基本描述 # [geo_polygon] unexpected token type [...] 说明 Elasticsearch 在解析 geo_polygon 查询时，当前读取到的 JSON token 与语法预期不一致。常见情况是本应读取点数组、对象或字段值时，结果遇到了错误层级的字段名、字符串、数字或其他 token。 常见现象 # … - [invalid time minute value expected string/number but found - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/invalid-time-minute-value-expected-string-number-value-but-found-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.17 1. 错误异常的基本描述 # invalid time minute value. expected string/number value; but found [token] 是 Elasticsearch Watcher 功能中的配置错误。当你在定义 Watcher 的定时调度（schedule）时，如果 minute 字段的值不是字符串或数字类型（比如传入 … - [Management 线程池保活时间配置](https://easysearch.cn/knowledge-base/easysearch_config/thread_pool.management.keep_alive/): 配置项作用 # thread_pool.management.keep_alive 配置项用于控制管理线程池中弹性线程的保活时间。 配置项属性 # 配置路径: thread_pool.management.keep_alive 数据类型: TimeValue（时间值） 默认值: 5m（5 分钟） 是否可选: 是 作用域: NodeScope（节点级别） 动态更新: 是（可以动态更新，无需重 … - [Percolator 字段不能直接搜索，请使用 percolate 查询 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/percolator-fields-are-not-searchable-directly-use-a-percolate-query-instead-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Percolator 字段不能直接搜索，请使用 percolate 查询 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现 … - [RareTerms 聚合无法应用于字段 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/rareterms-aggregation-cannot-be-applied-to-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.3-7.7 1. 错误异常的基本描述 # RareTerms 聚合无法应用于字段 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [TCP Keepalive 探测次数配置](https://easysearch.cn/knowledge-base/easysearch_config/network.tcp.keep_count/): 配置项作用 # network.tcp.keep_count 配置项用于控制TCP keepalive 机制中探测包的最大发送次数。 当启用 TCP keepalive 后，如果连接在指定时间内没有收到响应，系统会发送 keepalive probe。此配置决定了在放弃连接之前最多发送多少个探测包。 配置项属性 # 配置路径: network.tcp.keep_count 数据类型: … - [Transport Netty 接收缓冲区预测大小配置](https://easysearch.cn/knowledge-base/easysearch_config/transport.netty.receive_predictor_size/): 配置项作用 # transport.netty.receive_predictor_size 配置项用于定义Netty 接收缓冲区大小预测的基础值。 配置项属性 # 配置路径: transport.netty.receive_predictor_size 数据类型: ByteSizeValue（字节大小，支持 bytes、kb、mb、gb 单位） 默认值: 64kb 是否可选: 是 作用域: … - [Unsupported token token - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unsupported-token-token-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Unsupported token token 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [不支持的连接键 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unsupported-join-key-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.9-8.9 1. 错误异常的基本描述 # 不支持的连接键 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [分片已关闭且恢复已取消原因原因——如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/shard-is-closed-and-recovery-was-canceled-reason-reason-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 分片已关闭且恢复已取消原因原因— 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [区间不支持小数值 – 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/fractional-values-are-not-supported-for-intervals-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 区间不支持小数值 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [启动角色映射文件监视器失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-start-file-watcher-for-role-mapping-file-file-toabsolutepath-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # failed to start file watcher for role mapping file [<path>] 表示 Elasticsearch 在安全模块初始化基于文件的角色映射（role mapping）配置时，无法为指定的角色映射文件或其父目录注册文件监视服务（File Watcher）。 角色映射文件通常用于 … - [在偏移位置预期分组分隔符但发现了其他字符 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/expected-group-separator-at-offset-found-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # 在偏移位置预期分组分隔符但发现了其他字符 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [搜索解析异常 (search_parse_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/search_parse_exception/): 为什么这个错误发生 # search_parse_exception 表示搜索查询解析失败。 如何修复 # 1. 验证查询语法 # GET /<index>/_validate/query?explain { "query": { "match": { "field": "value" } } } 2. … - [无法打开 Data Frame Analytics - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-open-data-frame-analytics-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.3-7.4 1. 错误说明 # Cannot open data frame analytics [id] because it has already been opened 表示指定的 Data Frame Analytics 任务已经处于打开状态，再次调用 open 接口时触发了冲突异常。该异常由 Elasticsearch 内部在检测到资源已存在时抛出，HTTP 状态码 … - [无法获取不兼容快照的状态 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-get-the-status-for-an-incompatible-snapshot-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.3 1. 错误异常的基本描述 # cannot get the status for an incompatible snapshot 表示 Elasticsearch 已经找到了目标 snapshotId，但发现它位于 repositoryData.getIncompatibleSnapshotIds() 中，因此拒绝进一步查询该快照状态， … - [无法解析消息附件字段，解析字段失败 (Could not parse message attachment field failed to parse field) - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-message-attachment-field-failed-to-parse-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # 无法解析消息附件字段，解析字段失败 (Could not parse message attachment field failed to parse field) 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性 … - [无法迁移因为索引不存在 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-migrate-because-that-index-does-not-exist-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.16-8.9 1. 错误异常的基本描述 # 无法迁移因为索引不存在 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [日期字段不能为 null - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-date-time-expected-date-field-to-not-be-null-but-was-null-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # could not parse date/time expected date field [field] to not be null but was null 是 Elasticsearch 在解析日期字段时抛出的异常，表示当前解析路径要求日期字段必须有值，但请求中该字段的值为 null。 … - [更新索引映射](https://easysearch.cn/knowledge-base/easysearch_api/update-index-mapping/): 更新一个或多个索引的映射定义，添加新字段或修改现有字段配置。 API # PUT /{index}/_mapping POST /{index}/_mapping API 的作用 # 该 API 用于更新索引的映射（mapping）定义，支持以下操作： 添加新字段：为索引添加新的字段及其类型定义 更新字段配置：修改某些字段的可更新属性 合并映射： … - [未找到ID为id的分块文档 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/chunk-document-with-id-id-not-found-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.13-8.9 1. 错误异常的基本描述 # 未找到ID为id的分块文档 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [未指定时间单位，是指s（秒）吗——如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/no-time-unit-specified-did-you-mean-s-as-in-s-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.8-7.15 1. 错误异常的基本描述 # 未指定时间单位，是指s（秒）吗— 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [解析 Watch Input 时 HTTP 请求模板解析失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-input-for-watch-failed-to-parse-http-request-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # could not parse [TYPE] input for watch [watchId]. failed to parse http request template 表示 Elasticsearch 在解析 Watcher 的 HTTP input 时，其内部的 request 模板对象解析失败。 … - [认证没有验证领域 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/authentication-has-no-authenticating-realm-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.2-8.9 1. 错误说明 # authentication has no authenticating realm（认证没有验证领域）是 Elasticsearch 安全模块在认证过程中抛出的异常。当系统无法为当前认证请求找到对应的验证领域（Realm）时触发此错误，表明用户身份无法通过任何已配置的安全域进行验证。 … - [远程集群初始连接超时配置](https://easysearch.cn/knowledge-base/easysearch_config/cluster.remote.initial_connect_timeout/): 配置项作用 # cluster.remote.initial_connect_timeout 配置项用于控制节点启动时建立到远程集群初始连接的超时时间。 当 Easysearch 节点启动时，如果配置了远程集群，系统会尝试与这些远程集群建立连接。此配置决定了等待这些初始连接建立完成的最长时间。 配置项属性 # 配置路径: … - [验证查询](https://easysearch.cn/knowledge-base/easysearch_api/validate-query/): 验证查询语句是否有效，检查查询语法和参数，不实际执行查询。 API # GET /_validate/query POST /_validate/query GET /{index}/_validate/query POST /{index}/_validate/query API 的作用 # 该 API 用于验证查询语句的有效性，帮助调试和优化查询。 验证 API 的功能 # 功能 … - [assignment for model with id already exists - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/assignment-for-model-with-id-already-exists-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.17-8.9（含 Machine Learning 特性的版本） 1. 错误说明 # assignment for model with id [<model_id>] already exists 是 Elasticsearch 机器学习模块在部署或分配训练好的模型（Trained Model）时抛出的异常。该错误表明：当前集群中已存在针对同一模型 ID 的活跃分 … - [Easysearch 2.0 版本新特性解读](https://easysearch.cn/knowledge-base/basic/easysearch-2.0-new-features/): 在基础设施软件领域，底层内核的升级往往意味着性能的质变。 近日，INFINI Easysearch 2.0 正式发布。最引人注目的变化，莫过于其底层核心——Apache Lucene 的版本从 8.11.4 跨越式升级到了 9.12.0。 这不仅仅是一个版本号的跳变，更代表了 Easysearch 正式拥抱 JDK 21 和 原生向量检索时代。本文将从内核升级、AI 能力、性能压榨和易用性四个维 … - [Geo-point 字段类型不支持超过3个维度——如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/geo-point-field-type-does-not-accept-3-dimensions-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # Geo-point 字段类型不支持超过3个维度— 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返 … - [HTTP Netty 复合缓冲区组件数配置](https://easysearch.cn/knowledge-base/easysearch_config/http.netty.max_composite_buffer_components/): 配置项作用 # http.netty.max_composite_buffer_components 配置项控制 Netty 复合缓冲区（CompositeByteBuf）中最大组件数量。这用于优化 HTTP 请求块聚合时的内存使用。 默认值 # 动态计算（基于 maxContentLength 和 MTU） 配置类型 # 静态配置 取值范围 # 2 ~ Integer.MAX_VALUE … - [Invalid azure client settings with name [clientName] - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/invalid-azure-client-settings-with-name-clientname-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # Invalid azure client settings with name [clientName] 表示 Elasticsearch 已经找到了对应 client 名，但在构建 Azure 客户端时因为密钥、URI 或其他参数不合法而失败。 常见现象 # Azure 仓库初始化立即失败。 … - [Jira 账户配置缺少必需设置 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/invalid-jira-account-account-settings-missing-required-setting-setting-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # Watcher 在发送 Jira issue 前，会先加载对应的 Jira account。只要账户级必填配置缺失，Elasticsearch 就会直接抛出 invalid jira [account] account settings. missing required [setting] setting。 这类错误通常发生在账户初 … - [NAME 索引中未找到 join 字段 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/name-no-join-field-found-for-index-indexname-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # NAME 索引中未找到 join 字段 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [主查询执行失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-execute-main-query-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # 主查询执行失败 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [事务日志滚动失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-roll-translog-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 事务日志滚动失败 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [分片已启动 (index_shard_started_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/index_shard_started_exception/): 为什么这个错误发生 # index_shard_started_exception 表示尝试对一个已经启动的分片执行启动操作。 如何修复 # 1. 检查分片状态 # GET /_cat/shards?v 2. 无需操作 # 分片已启动是正常状态。 3. 如果需要重启 # POST /_cluster/reroute { "commands": [{ … - [创建索引别名](https://easysearch.cn/knowledge-base/easysearch_api/create-index-alias/): 为一个或多个索引创建别名，别名可用于简化索引访问、实现零停机重建等场景。 API # PUT /{index}/_alias/{name} POST /{index}/_alias/{name} PUT /{index}/_alias/{name} PUT /_alias/{name} PUT /_alias/{name} API 的作用 # 为索引创建别名，别名是索引的替代名称，可以指向单个 … - [发现未知的标记 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unknown-token-found-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 发现未知的标记 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [当前JDK不支持线程分配内存 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/thread-allocated-memory-is-not-supported-on-this-jdk-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.16-8.9 1. 错误异常的基本描述 # 当前JDK不支持线程分配内存 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [按数据节点数量恢复配置](https://easysearch.cn/knowledge-base/easysearch_config/gateway.recover_after_data_nodes/): 配置项作用 # gateway.recover_after_data_nodes 配置项用于指定集群恢复状态所需要的最少数据节点数量。 当集群启动时，只有在达到指定数量的数据节点后，才会开始恢复集群状态和分片数据。 配置项属性 # 配置路径: gateway.recover_after_data_nodes 数据类型: integer 默认值: -1（表示禁用此条件） 最小值: -1 是否可 … - [提供了无效的数据类型 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/invalid-data-type-provided-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # 提供了无效的数据类型 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [搜索要删除的预测时发生错误 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/an-error-occurred-while-searching-forecasts-to-delete-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 搜索要删除的预测时发生错误 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无可用连接 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/no-connection-available-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.8-8.9 1. 错误异常的基本描述 # 无可用连接 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返回 400、404、409、429、500 … - [无法为 Rollup Job 启动任务，因为当前状态不允许 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-start-task-for-rollup-job-job-getconfig-getid-because-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # Cannot start task for Rollup Job [xxx] because state was [xxx] 表示在尝试启动 Rollup Job 时，底层 Indexer 的当前状态不是 STOPPED，因此任务启动请求被拒绝。Rollup 任务的启动逻辑要求必须先处于 STOPPED 状态， … - [无法为 SAML IdP 设置上下文类加载器 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-set-context-classloader-for-saml-idp-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.7-8.9 1. 错误异常的基本描述 # 无法为 SAML IdP 设置上下文类加载器 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法管理集群警报，因为导出器已终止 – 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-manage-cluster-alerts-because-exporter-is-terminated-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.11-8.9 1. 错误异常的基本描述 # 无法管理集群警报，因为导出器已终止 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法解析文档中指定类型的字段 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-field-of-type-in-document-with-id-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # 无法解析文档中指定类型的字段 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法解析节点外部ID - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-resolve-node-external-ids-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.6-8.11 1. 错误异常的基本描述 # 无法解析节点外部ID 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法验证响应，用户会话未包含状态参数 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-validate-the-response-the-user-s-session-did-not-contain-a-state-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.2-7.15 1. 错误异常的基本描述 # 无法验证响应，用户会话未包含状态参数 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [日期字段必须是数字或字符串 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-date-time-expected-date-field-to-be-either-a-number-or-a-string-but-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.17 1. 错误异常的基本描述 # could not parse date/time. expected date field [field] to be either a number or a string but found [token] instead 是 Elasticsearch 在解析日期字段时抛出的异常，表示传入的字段值类型不符合日期解析器的预期。 … - [更新文档](https://easysearch.cn/knowledge-base/easysearch_api/update-document/): 部分更新指定 ID 的文档，支持使用脚本或字段更新。 API # POST /{index}/_update/{id} API 的作用 # 该 API 用于部分更新文档，与 /_doc API（完全替换）不同，此 API 只修改指定的字段。 更新方式 # 方式 描述 Doc 更新 直接提供要更新的字段 Script 更新 使用脚本动态更新文档 核心特性 # 特 … - [没有名为且类型为OBJECT的参数 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/no-parameter-named-and-type-object-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 没有名为且类型为OBJECT的参数 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [源分片已关闭 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/source-shard-is-closed-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 源分片已关闭 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [源节点在其状态中没有将分片列为已分配在该节点上 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/source-node-does-not-have-the-shard-listed-in-its-state-as-allocated-on-the-node-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 源节点在其状态中没有将分片列为已分配在该节点上 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返 … - [用索引别名，让 Easysearch 支持无感升级](https://easysearch.cn/knowledge-base/usage/easysearch-index-alias-seamless-upgrade/): 在企业级搜索架构中，唯一不变的就是“变化”。随着业务发展，我们经常面临这样的需求：修改索引的分片数（Shards）、调整字段类型（Mapping）、开启 Easysearch 特有的 ZSTD 压缩以节省成本，甚至是将底层引擎从旧版 Elasticsearch 迁移到 Easysearch。 在传统做法中，修改索引结构通常意味着：停机 -> 重建索引 -> 导数据 -> 修改代码 … - [线程池时间缓存更新间隔配置](https://easysearch.cn/knowledge-base/easysearch_config/thread_pool.estimated_time_interval/): 配置项作用 # thread_pool.estimated_time_interval 配置项用于控制时间缓存线程的更新间隔。 Easysearch 使用一个专门的守护线程（CachedTimeThread）来缓存系统时间，避免频繁调用系统时间函数。此配置决定缓存时间的更新频率。 配置项属性 # 配置路径: thread_pool.estimated_time_interval 数据类型: … - [编译错误 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/compile-error-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 编译错误 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返回 400、404、409、429、500 … - [节点搜索缓存大小配置](https://easysearch.cn/knowledge-base/easysearch_config/node.search.cache.size/): 配置项作用 # node.search.cache.size 配置项控制节点上用于缓存搜索结果的内存大小。 是否可选 # 是 默认值 # 100mb 配置项类型 # 静态配置 - 需要重启节点才能生效 配置格式 # # 默认配置 node.search.cache.size: 100mb # 增加缓存 node.search.cache.size: 200mb # … - [被中断 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/interrupted-by-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.3-7.17 1. 错误异常的基本描述 # 被中断 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返回 400、404、409、429、500 … - [请求缓存过期时间配置](https://easysearch.cn/knowledge-base/easysearch_config/indices.requests.cache.expire/): 配置项作用 # indices.requests.cache.expire 配置项控制请求缓存的过期时间。设置后，缓存在指定时间后自动失效。 默认值 # 0ms（不过期） 配置类型 # 静态配置 配置格式 # # 默认配置：不过期 indices.requests.cache.expire: 0ms # 设置过期时间 indices.requests.cache.expire: 5m # … - [连接已关闭 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/connection-already-closed-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 连接已关闭 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返回 400、404、409、429、500 … - [a primary endpoint is required when setting a secondary endpoint - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/a-primary-endpoint-is-required-when-setting-a-secondary-endpoint-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.8-8.9 1. 错误异常的基本描述 # A primary endpoint is required when setting a secondary endpoint 是 Elasticsearch 在配置 Azure Blob Storage 快照仓库（snapshot repository）时抛出的配置错误。当你为 Azure … - [attachment with id has already been created must be renamed - 附件 ID 冲突必须重命名如何解决](https://easysearch.cn/knowledge-base/elasticsearch_error/attachment-with-id-has-already-been-created-must-be-renamed-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.x 1. 错误异常的基本描述 # Attachment with id [...] has already been created; must be renamed 表示 Elasticsearch Watcher 在解析附件集合时，发现某个新附件的 id 已经被同一请求中的其他附件占用，导致附件解析失败。这是一个 ID 冲突异常，发生在 Watcher 的附件解析阶 … - [Has privilege task cancelled – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/has-privilege-task-cancelled-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.4-8.9 1. 错误异常的基本描述 # Has privilege task cancelled 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能 … - [header 配置缺少值 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/headers-must-have-values-missing-for-setting-concretesetting-getkey-name-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # headers must have values; missing for setting [settingName] 是 Elasticsearch 在解析配置时抛出的 SettingsException。当某个 header 相关的设置项被声明，但最终解析出来的值列表为空时，就会触发此异常。 常见现象 # … - [HTTP TCP Keep-Alive 空闲时间配置](https://easysearch.cn/knowledge-base/easysearch_config/http.tcp.keep_idle/): 配置项作用 # http.tcp.keep_idle 配置项用于控制在连接空闲多长时间后，TCP Keep-Alive 机制开始发送探测包。 这是 TCP Keep-Alive 机制的第一个参数，定义了连接在没有任何数据传输的情况下保持活跃状态的时间，超过这个时间后才会开始发送 Keep-Alive 探测包。 配置项属性 # 配置路径: http.tcp.keep_idle 数据类型: … - [HTTP TCP NoDelay 配置](https://easysearch.cn/knowledge-base/easysearch_config/http.tcp.no_delay/): 配置项作用 # http.tcp.no_delay 配置项用于控制是否禁用 TCP Nagle 算法。 Nagle 算法是一种通过缓冲小数据包来提高网络利用率的算法。禁用它（设置 no_delay = true）可以使数据立即发送，减少网络延迟。 配置项属性 # 配置路径: http.tcp.no_delay 数据类型: Boolean（布尔值） 默认值: true 是否可选: 是 作用域: … - [ILM 协调器清理周期配置](https://easysearch.cn/knowledge-base/easysearch_config/index_lifecycle_management.coordinator.sweep_period/): 配置项作用 # index_lifecycle_management.coordinator.sweep_period 配置项用于控制索引生命周期管理（ILM）协调器执行后台清理任务的时间间隔。 协调器会定期检查所有托管索引的状态，确保索引按照预定义的策略正确执行，并在出现异常时自动恢复。 配置项属性 # 配置路径: … - [Key已设置但type为dependency – 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/key-is-set-but-type-is-dependency-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.6-8.9 1. 错误异常的基本描述 # Key已设置但type为dependency 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Murmur3字段不可搜索 name - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/murmur3-fields-are-not-searchable-name-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.1 1. 错误异常的基本描述 # Murmur3字段不可搜索 name 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [NAME no join field has been configured - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/name-no-join-field-has-been-configured-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # NAME no join field has been configured 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常 … - [Pipeline - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/pipeline-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # Pipeline 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Processor type – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/processor-type-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Processor type 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [REST请求尝试注入用户 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/rest-request-attempted-to-inject-a-user-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # REST请求尝试注入用户 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Transport Netty 接收缓冲区预测最小值配置](https://easysearch.cn/knowledge-base/easysearch_config/transport.netty.receive_predictor_min/): 配置项作用 # transport.netty.receive_predictor_min 配置项用于定义Netty 接收缓冲区分配器的最小预测值。 配置项属性 # 配置路径: transport.netty.receive_predictor_min 数据类型: ByteSizeValue（字节大小，支持 bytes、kb、mb、gb 单位） 默认值: … - [Unexpected token - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unexpected-token-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # unexpected token 是 Elasticsearch 在解析请求体时抛出的 ParsingException 异常，表示 XContentParser 在读取 JSON/YAML 内容时遇到了不符合预期类型的 token。该异常通常发生在请求体结构不正确、字段类型不匹配或嵌套层级错误时，Elasticsearch 无法按照预 … - [不再是当选的主节点 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/no-longer-the-elected-master-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.16-8.9 1. 错误异常的基本描述 # 不再是当选的主节点 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [不知道如何解析 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/don-t-know-how-to-parse-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 不知道如何解析 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [任务被取消 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/task-was-cancelled-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.17-8.9 1. 错误异常的基本描述 # 任务被取消 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返回 400、404、409、429、500 … - [分片分配解释](https://easysearch.cn/knowledge-base/easysearch_api/shard-allocation-explanation/): 解释集群中分片的分配决策，帮助用户理解为什么某个分片会被分配到特定的节点，或者为什么某个分片没有被分配。 API # GET /_cluster/allocation/explain POST /_cluster/allocation/explain API 的作用 # 该 API 用于解释集群中分片（shard）的分配决策，帮助用户： 理解为什么某个分片被分配到特定节点 查看为什么某个分片 … - [创建收集器时发生IO错误 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/io-error-creating-collector-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 创建收集器时发生IO错误 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [打开作业 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/opening-job-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.1 1. 错误异常的基本描述 # 打开作业 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返回 400、404、409、429、500 … - [无法序列化 ID 为 job getId 的作业 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-serialise-job-with-id-job-getid-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 无法序列化 ID 为 job getId 的作业 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法解析地址 (could not parse field as address) - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-field-as-address-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 无法解析地址 (could not parse field as address) 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判 … - [无法解析模型定义，因为内容超过了最大流大小 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-parse-model-definition-as-the-content-is-larger-than-the-maximum-stream-size-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.11-7.15 1. 错误异常的基本描述 # 无法解析模型定义，因为内容超过了最大流大小 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法解码加密数据 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unable-to-decode-encrypted-data-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 无法解码加密数据 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [未找到ID为id且分配ID为allocationId的任务 – 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/the-task-with-id-id-and-allocation-id-allocationid-not-found-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 未找到ID为id且分配ID为allocationId的任务 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [未知的同步刷新结果 result - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unknown-synced-flush-result-result-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.17 1. 错误异常的基本描述 # 未知的同步刷新结果 result 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [没有已知具有指定部署ID的训练模型 – 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/no-known-trained-model-with-deployment-with-id-how-to-solve-this-elasticsearch-exception/): 适用版本： 8-8.5 1. 错误异常的基本描述 # 没有已知具有指定部署ID的训练模型 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [版本冲突 (version_conflict_engine_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/version_conflict_engine_exception/): 为什么这个错误发生 # version_conflict_engine_exception 表示在尝试更新或删除文档时发生版本冲突。这是 Easysearch 的乐观并发控制机制在工作，用于防止多个并发操作覆盖彼此的更改。 这个错误可能由以下原因引起： 并发更新：多个客户端同时尝试更新同一个文档 版本号不匹配：使用的版本号与文档当前版本号不一致 文档已被删除：尝试更新一个已被删除的文档 使用外 … - [理解 Easysearch 倒排索引：为什么搜索这么快？](https://easysearch.cn/knowledge-base/basic/easysearch-inverted-index-explained/): 搜索引擎最引以为豪的能力是什么？ 不是数据库那样的行扫描、也不是简单的结构化索引，而是能够在海量文本中极快地找到关键词对应的相关文档。这背后的核心秘密就是——倒排索引（Inverted Index）。 在 Easysearch 中，搜索速度之所以快，与倒排索引密不可分。理解它的原理有助于你更合理地设计索引、写查询和分析性能瓶颈。 一、Easysearch 是什么？ # Easysearch 是 … - [获取索引列表](https://easysearch.cn/knowledge-base/easysearch_api/get-index-list/): 以表格形式显示集群中索引的信息概览，包括健康状态、分片数量、文档数量、存储大小等。 API # GET /_cat/indices GET /_cat/indices/{index} API 的作用 # 该 API 以简洁的表格形式显示索引的各种统计信息，便于快速了解集群中的索引状况。 默认显示的列 # 列名 描述 health 索引健康状态（green、yellow、red） … - [路由缺失异常 (routing_missing_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/routing_missing_exception/): 为什么这个错误发生 # routing_missing_exception 表示执行操作时缺少必需的路由信息。路由（routing）值用于确定文档存储在哪个分片上，某些操作需要明确指定路由值。 这个错误可能由以下原因引起： 缺少路由参数：请求中未提供必需的路由值 自定义路由映射：索引配置了自定义路由映射 父文档关系：使用父子关系时需要路由值 分片路由：操作需要特定分片但未提供路由 客户端配置错 … - [集群发现机制配置](https://easysearch.cn/knowledge-base/easysearch_config/discovery.type/): 配置项作用 # discovery.type 配置项指定节点使用的集群发现机制类型。发现机制决定节点如何找到其他节点并组成集群。 配置项类型 # 该配置项为静态配置，需要在启动时设置，修改后需要重启节点才能生效。 默认值 # zen（Zen 发现机制） 是否必需 # 可选配置项（有默认值） 可选值 # 值 说明 zen Zen 发现机制（默认，适用于多节点集群） … - [a filter with id filter getid already exists - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/a-filter-with-id-filter-getid-already-exists-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.16-8.9 1. 错误异常的基本描述 # a filter with id [filter_getid] already exists 是 Elasticsearch 在管理保存的过滤器（saved filters）或 percolator 查询时抛出的异常。当你尝试创建一个指定 ID 的过滤器或 percolator 查询，但该 ID 已经被现有过滤器使用时，就会触发此错 … - [dynamic attachments 的 list_path 必须是字符串 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-dynamic-attachments-expected-a-string-value-for-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # could not parse dynamic attachments. expected a string value for [list_path] field 是 Elasticsearch 在解析 Ingest Pipeline 中 dynamic attachments 处理器配置时抛出的解析异常。 … - [Easysearch：第一次用 Aggregations，就能做出报表级统计](https://easysearch.cn/knowledge-base/basic/easysearch-aggregations-reporting-statistics/): 在很多团队中，搜索引擎最早承担的角色只是“查数据”。 但当数据量变大、业务问题变复杂，仅靠列表查询已经远远不够——我们开始需要统计、汇总和分析。 Easysearch 提供的 Aggregations（聚合分析），正是用来解决这类问题的核心能力。即使是第一次接触，只要掌握几个基础概念，也可以直接做出报表级别的统计结果。 本文将从零开始，带你理解并使用 Easysearch … - [Elasticsearch API 兼容版本配置](https://easysearch.cn/knowledge-base/easysearch_config/elasticsearch.api_compatibility_version/): 配置项概述 # elasticsearch.api_compatibility_version 配置项指定 Easysearch 兼容的 Elasticsearch 版本号。 配置项 默认值 说明 elasticsearch.api_compatibility_version 7.10.2 ES API 兼容版本 配置说明 # … - [Expected word but found - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/expected-word-but-found-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Expected word but found 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [ISM 历史索引分片数配置](https://easysearch.cn/knowledge-base/easysearch_config/index_state_management.history.number_of_shards/): 配置项作用 # index_state_management.history.number_of_shards 配置项用于控制索引状态管理（ISM）历史索引的主分片数量。 历史索引用于存储 ISM 策略执行的记录。分片数影响历史索引的并发写入性能和查询性能。 配置项属性 # 配置路径: index_state_management.history.number_of_shards 数据类型: … - [JVM GC 开销警告阈值配置](https://easysearch.cn/knowledge-base/easysearch_config/monitor.jvm.gc.overhead.warn/): 配置项作用 # monitor.jvm.gc.overhead.warn 配置项用于控制JVM 垃圾回收（GC）开销的 WARN 级别日志阈值。 当 GC 开销（GC 时间占总时间的百分比）达到或超过此阈值时，系统会记录 WARN 级别的日志，警告严重的 GC 问题，需要立即关注和处理。 配置项属性 # 配置路径: monitor.jvm.gc.overhead.warn 数据类型: … - [Query string analyzer not found – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/query-string-analyzer-analyzer-not-found-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Query string analyzer not found 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Span prefix查询 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/span-prefix-query-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.3-8.9 1. 错误异常的基本描述 # Span prefix查询 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [仅当分片状态为指定状态时才允许操作 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/operations-only-allowed-when-shard-state-is-one-of-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # 仅当分片状态为指定状态时才允许操作 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [传输层操作未找到异常 (action_not_found_transport_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/action_not_found_transport_exception/): 为什么这个错误发生 # action_not_found_transport_exception 表示通过传输层发送的操作请求在目标节点上没有对应的处理器。这通常意味着目标节点不支持该操作或版本不兼容。 这个错误可能由以下原因引起： 版本不兼容：节点间的版本不一致，某些操作在不同版本间不兼容 插件未安装：操作需要特定插件支持，但目标节点未安装 节点状态异常：目标节点正在启动或关闭过程中 操作名 … - [删除最后一个分片shardId后未能删除未使用的索引 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-delete-unused-index-after-deleting-its-last-shard-shardid-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # 删除最后一个分片shardId后未能删除未使用的索引 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接 … - [在选项中检测到重复选项 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/duplicate-option-detected-in-options-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 在选项中检测到重复选项 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [字段别名的路径值无效 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/invalid-path-value-path-for-field-alias-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # 字段别名的路径值无效 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [执行词向量请求失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-execute-term-vector-request-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 执行词向量请求失败 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [找不到匹配 issuer 的 OpenID Connect Realm - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-find-openid-connect-realm-with-issuer-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.2-8.9 1. 错误异常的基本描述 # Cannot find OpenID Connect realm with issuer [issuer] 表示 Elasticsearch 在安全认证流程中，无法找到与当前请求携带的 issuer 值相匹配的 OpenID Connect Realm 配置。该异常通常发生在用户通过 OIDC 方式登录 Elasticsearch … - [搜索源构建器异常 (search_source_builder_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/search_source_builder_exception/): 为什么这个错误发生 # search_source_builder_exception 表示搜索源构建失败。 如何修复 # 1. 检查查询参数 # 确保搜索请求参数正确。 2. 使用简单查询 # GET /<index>/_search { "query": { "match_all": {} } } 预防措施 # 验证查询语法 - [无法删除测试数据 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-delete-test-data-at-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 无法删除测试数据 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法解析节点名称 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-resolve-node-names-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.6-8.11 1. 错误异常的基本描述 # 无法解析节点名称 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [期望分配 ID 和 term 但发现不同的值 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/expected-allocation-id-with-term-but-found-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # 期望分配 ID 和 term 但发现不同的值 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [未找到值 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/no-found-for-value-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 未找到值 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返回 400、404、409、429、500 … - [未找到请求用户拥有的ID为apiKeyId的API密钥 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/no-api-key-owned-by-requesting-user-found-for-id-apikeyid-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.4-8.4 1. 错误异常的基本描述 # 未找到请求用户拥有的ID为apiKeyId的API密钥 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返 … - [构建 inner_hits 失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-build-inner-hits-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # failed to build inner_hits 是 Elasticsearch 在执行搜索请求时，主查询已经匹配到文档，但在为嵌套（nested）或父子（parent-child）查询构建 inner_hits 子结果阶段抛出的异常。该异常通常出现在协调节点（coordinating node）汇总各分片返回结果的过程中，意味着某 … - [构建实体时发生意外错误](https://easysearch.cn/knowledge-base/elasticsearch_error/unexpected-error-building-entity-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 构建实体时发生意外错误 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [查询字符串不包含 SAMLRequest 参数 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/query-string-does-not-contain-a-samlrequest-parameter-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.7-7.15 1. 错误异常的基本描述 # 查询字符串不包含 SAMLRequest 参数 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [查询所有数据流](https://easysearch.cn/knowledge-base/easysearch_api/get-all-data-streams/): 此 API 用于获取 Easysearch 集群中数据流（Data Stream）的详细信息。可以查询所有数据流，也可以通过名称过滤获取特定数据流。 API # GET /_data_stream API 的作用 # 获取数据流的元数据信息，包括： 数据流名称：数据流的唯一标识符 时间戳字段配置：数据流使用的时间戳字段名称 底层索引列表：构成数据流的所有后备索引 生成号：数据流的当前生成版本 … - [第二阶段失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/phase2-failed-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.8 1. 错误异常的基本描述 # 第二阶段失败 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [缺失分片响应 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/missing-shard-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.12-8.9 1. 错误异常的基本描述 # missing shard 是 Elasticsearch 在执行 downsample（下采样） 任务时抛出的异常，表示协调节点在汇总各分片返回结果时，发现 shardsResponses 数组中某个位置本应有分片响应，实际却拿到了 null。这个错误不是普通搜索里的"找不到分片"，而是后台任务在遍历分片级执行结 … - [聚合父名称不能拥有全局子聚合 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/aggregation-parent-name-cannot-have-a-global-sub-aggregation-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Aggregation [parent_name] cannot have a global sub-aggregation 是 Elasticsearch 聚合查询中的特定异常，表示在聚合定义中，尝试将 global 聚合作为某个父聚合的子聚合（sub-aggregation）使用，而这是不被允许的。 错误含义 # global 聚 … - [节流搜索线程池配置](https://easysearch.cn/knowledge-base/easysearch_config/thread_pool.search_throttled/): 配置项作用 # thread_pool.search_throttled 相关配置项控制用于执行节流搜索操作的线程池。节流搜索是指那些被标记为低优先级或对系统资源敏感的搜索请求，这些搜索会被分配到专用的节流线程池中，避免影响正常的搜索操作。 配置项类型 # 该配置项为静态配置，需要在启动时设置，修改后需要重启节点才能生效。 默认值 # … - [获取基本信息](https://easysearch.cn/knowledge-base/easysearch_api/get-basic-info/): 获取 Easysearch 节点的基本信息，包括节点名称、集群名称、集群 UUID、版本信息等。 API # GET / HEAD / API 的作用 # 该 API 用于快速了解 Easysearch 节点的基本信息和版本状态，是集群管理中最基础的接口之一。 返回的信息包括： 节点名称 (name) 集群名称 (cluster_name) 集群 UUID (cluster_uuid) 版本 … - [解析 Action Status 时出现未预期字段 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-action-status-for-unexpected-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # could not parse action status for [watchId/actionId]. unexpected field [field] 表示 Elasticsearch 在解析 Watcher 的 action status 时，遇到了当前解析器不支持的字段名。 该异常属于解析阶段的失败， … - [请求的功能状态 featuresNotOnThisNode 存在于 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/requested-feature-states-featuresnotonthisnode-are-present-in-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.12-7.13 1. 错误异常的基本描述 # requested feature states [...] are present in snapshot but those features are not installed on the current master node 表示快照里确实包含了你请求恢复的 feature states，但当前 master 节点并没有 … - [跟随者分片并发写入数配置](https://easysearch.cn/knowledge-base/easysearch_config/replication.follower.concurrent_writers_per_shard/): 配置项作用 # replication.follower.concurrent_writers_per_shard 配置项用于控制每个分片的复制并发写入线程数。 此配置决定了将复制操作写入 Follower 索引的并发度，直接影响复制的写入性能和资源消耗。 配置项属性 # 配置路径: replication.follower.concurrent_writers_per_shard 数据类 … - [a data frame analytics with id already exists - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/a-data-frame-analytics-with-id-already-exists-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.3-8.9 1. 错误异常的基本描述 # a data frame analytics with id already exists 是 Elasticsearch 机器学习功能中的异常。当你尝试创建一个新的数据框分析（Data Frame Analytics）作业，但指定的作业 ID 已经被现有作业使用时，就会触发此错误。数据框分析是 Elasticsearch 中用于分类、 … - [Easysearch：Bucket 和 Metric 聚合，看完这一篇就够了](https://easysearch.cn/knowledge-base/basic/easysearch-bucket-and-metric-aggregations/): 1. 什么是 Easysearch？ # Easysearch 是一款现代分布式搜索与分析引擎，支持全文检索、结构化检索、聚合分析等能力。它能够处理大规模文档数据，通过灵活的搜索与统计能力帮助开发者构建实时分析、报表展示、业务监控等功能。Easysearch 的聚合功能设计来源于 Elasticsearch 的 Aggregations 框架，可实现高效的数据统计与分组分析。 2. 聚合的基本 … - [Force Merge 线程池队列大小配置](https://easysearch.cn/knowledge-base/easysearch_config/thread_pool.force_merge.queue_size/): 配置项作用 # thread_pool.force_merge.queue_size 配置项用于控制强制合并线程池的队列大小。 当所有合并线程都在忙碌时，新的合并请求会被放入队列等待。 配置项属性 # 配置路径: thread_pool.force_merge.queue_size 数据类型: Integer（整数） 默认值: -1（无界队列） 是否可选: 是 作用域: NodeScope（ … - [HTTP TCP Keep-Alive 启用配置](https://easysearch.cn/knowledge-base/easysearch_config/http.tcp.keep_alive/): 配置项作用 # http.tcp.keep_alive 配置项用于控制HTTP 服务器是否启用 TCP Keep-Alive 机制。 TCP Keep-Alive 是一种网络连接保活机制，通过定期发送空的 TCP 探测包来保持连接活跃，检测已断开的连接，防止中间网络设备断开空闲连接。 配置项属性 # 配置路径: http.tcp.keep_alive 数据类型: Boolean（布尔值） 默 … - [Join target is a follower - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/join-target-is-a-follower-how-to-solve-this-elasticsearch-exception/): 适用版本： 7-8.9 1. 错误异常的基本描述 # Join target is a follower 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [More Like This 查询解析失败：未指定 id 或 doc 参数 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-more-like-this-item-neither-id-nor-doc-is-specified-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.16-8.9 1. 错误异常的基本描述 # failed to parse More Like This item. neither [id] nor [doc] is specified! 是 Elasticsearch 在执行 more_like_this 查询时抛出的解析异常。该错误表示在构造 More Like This 查询项时，既没有指定 id 也没有指定 doc … - [Recover snapshot files cancelled - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/recover-snapshot-files-cancelled-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.16-8.9 1. 错误异常的基本描述 # 在从快照恢复分片时，Elasticsearch 会并行下载和应用快照文件。如果发现某些下载失败，或者恢复中的文件状态与源索引文件不再一致，它会取消当前这一轮文件恢复，等待飞行中的请求收尾后再重置恢复流程。此时常见异常就是 Recover snapshot files cancelled。 常见现象 # 快照恢复过程中中断，但不是简 … - [事务日志被截断 (truncated_translog_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/truncated_translog_exception/): 为什么这个错误发生 # truncated_translog_exception 表示事务日志（translog）文件被截断或损坏。事务日志用于确保数据 durability。 这个错误可能由以下原因引起： 磁盘空间不足：写入时磁盘空间耗尽 异常关闭：节点异常关闭导致 translog 不完整 文件系统错误：底层文件系统错误 磁盘故障：磁盘硬件故障 如何修复这个错误 # 1. … - [使用特定许可证时必须显式启用安全性 – 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/security-must-be-explicitly-enabled-when-using-a-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # 使用特定许可证时必须显式启用安全性 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [字段 fieldName 不支持 ShapeType.POINT 查询 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/field-fieldname-does-not-support-shapetype-point-queries-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.16-8.9 1. 错误异常的基本描述 # 字段 fieldName 不支持 ShapeType.POINT 查询 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现 … - [字段名称发现不支持的形状 Line - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/field-name-found-an-unsupported-shape-line-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.12-8.2 1. 错误异常的基本描述 # 字段名称发现不支持的形状 Line 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [待处理状态过多 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/too-many-pending-states-pending-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.17 1. 错误异常的基本描述 # 待处理状态过多 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [快照没有段文件 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/snapshot-has-no-segments-file-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Snapshot has no segments file 表示 Elasticsearch 在恢复某个 shard 时，已经根据 snapshot metadata 构造出 Store.MetadataSnapshot，但调用 getSegmentsFile() 得到的是 null。由于 segments 文件是恢复 Lucene 索 … - [恢复快照 snapshotId 失败 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-restore-snapshot-snapshotid-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # failed to restore snapshot [snapshotId] 表示 Elasticsearch 已经为某个 shard 启动了恢复执行流程，但在真正从仓库恢复该分片数据时失败，最终抛出 IndexShardRestoreFailedException。这说明问题已经晚于“快照能否读取”“分片快照文件能否定位”的阶段，真 … - [搜索阶段执行异常 (search_phase_execution_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/search_phase_execution_exception/): 为什么这个错误发生 # search_phase_execution_exception 表示搜索的某个阶段执行失败，通常是由于部分分片失败。 如何修复 # 1. 检查失败的分片 # 错误响应包含 shardFailures 信息。 2. 检查分片状态 # GET /_cat/shards?v 3. 允许部分结果 # GET … - [操作被取消原因 reason —— 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/operation-was-cancelled-reason-reason-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 操作被取消原因 reason — 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无效包 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/invalid-package-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.8-8.9 1. 错误异常的基本描述 # 无效包 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返回 400、404、409、429、500 … - [无法初始化聚合器 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-initialize-aggregators-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # 无法初始化聚合器 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法启动 Datafeed，因为索引正在升级 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-start-datafeed-datafeedid-as-indices-are-being-upgraded-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # Could not start datafeed [datafeed_id] as indices are being upgraded 是 Elasticsearch 机器学习模块在集群处于升级模式时抛出的保护性异常。当集群正在对 ML 相关的系统索引（如 .ml-anomalies-*、.ml-state-*、.ml-meta-* … - [无法将 source 转换为 JSON 字符串 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-convert-source-to-a-json-string-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.x 1. 错误异常的基本描述 # failed to convert source to a json string 表示 Elasticsearch 在尝试将文档的 _source 字段以 JSON 字符串形式输出时失败。该异常通常发生在调用 XContentHelper.convertToJson(getSourceRef(), false) 时，如果 source … - [无法解析监视器触发事件，期望先读取触发器类型字段（Could not parse trigger event for ... expected trigger type string field）- 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-trigger-event-for-for-watch-expected-trigger-type-string-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.x 1. 错误异常的基本描述 # could not parse trigger event for [...] for watch [...]. expected trigger type string field; but found [...] 表示 Watcher 进入触发事件对象后，本来应该先读到一个字段名作为触发器类型，但实际遇到的 token 不是字段名。 … - [无法解析索引索引的阶段定义 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-phase-definition-for-index-index-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # 无法解析索引索引的阶段定义 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法解析节点路径 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unable-to-resolve-node-path-for-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.1 1. 错误异常的基本描述 # 无法解析节点路径 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [映射类型名称不能以下划线开头，除非称为 _doc —— 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/mapping-type-name-type-can-t-start-with-unless-it-is-called-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # 映射类型名称不能以下划线开头，除非称为 _doc — 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可 … - [更新索引设置](https://easysearch.cn/knowledge-base/easysearch_api/update-index-settings/): 更新或获取索引的设置配置。 API # GET /{index}/_settings GET /_all/_settings PUT /{index}/_settings PUT /_settings API 的作用 # GET /{index}/_settings # 获取一个或多个索引的当前设置，包括： 索引的分片和副本配置 索引的刷新间隔 分析器配置 其他索引级别的设置 PUT … - [更新集群设置](https://easysearch.cn/knowledge-base/easysearch_api/update-cluster-settings/): 更新集群的设置配置，支持持久化设置和临时设置两种类型。 API # PUT /_cluster/settings GET /_cluster/settings API 的作用 # 该 API 用于更新或获取集群的设置配置。Easysearch 支持两种类型的设置： 设置类型 描述 持久性 persistent（持久化设置） … - [期望数组值但未找到预期格式 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/expected-values-within-array-for-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.1-7.15 1. 错误异常的基本描述 # 期望数组值但未找到预期格式 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [未提供API密钥ID用于作废 – 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/no-api-key-ids-provided-for-invalidation-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 未提供API密钥ID用于作废 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [清扫器执行周期配置](https://easysearch.cn/knowledge-base/easysearch_config/jobscheduler.sweeper.period/): 配置项作用 # jobscheduler.sweeper.period 配置项用于控制作业清扫器（Job Sweeper）后台清理任务的执行间隔。 清扫器负责定期扫描所有作业索引，同步作业状态，确保作业调度的准确性。当集群状态发生变化时，清扫任务会重新同步作业信息，保证调度器与实际作业文档状态一致。 配置项属性 # 配置路径: jobscheduler.sweeper.period 旧版路 … - [生成过滤器失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-generate-filter-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 生成过滤器失败 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [索引模板名称指定了组件模板 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/index-template-name-specifies-component-templates-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.9-7.15 1. 错误异常的基本描述 # 索引模板名称指定了组件模板 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [网络层请求断路器内存限制配置](https://easysearch.cn/knowledge-base/easysearch_config/network.breaker.inflight_requests.limit/): 配置项作用 # network.breaker.inflight_requests.limit 配置项用于控制网络层飞行请求（in-flight requests）断路器的内存限制。 此断路器专门跟踪和处理网络上进行读写请求时分配的内存，防止网络传输层过度消耗内存导致系统崩溃。 配置项属性 # 配置路径: network.breaker.inflight_requests.limit 数据类 … - [聚合中出现未知属性路径 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unknown-property-path-for-aggtype-aggregation-aggname-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.16-8.9 1. 错误异常的基本描述 # 聚合中出现未知属性路径 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [节点本地存储节点数限制配置](https://easysearch.cn/knowledge-base/easysearch_config/node.max_local_storage_nodes/): 配置项作用 # node.max_local_storage_nodes 配置项限制在同一物理机器或同一 JVM 实例上可以启动的最大存储节点数量。 是否可选 # 是 默认值 # 1 (只允许 1 个存储节点) 配置项类型 # 静态配置 - 需要重启节点才能生效 配置格式 # # 默认配置（单个存储节点） node.max_local_storage_nodes: 1 # … - [a positive runs value is required found - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/a-positive-runs-value-is-required-found-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.16-8.9 1. 错误异常的基本描述 # a positive runs value is required [found] 是 Elasticsearch 在解析查询或配置时抛出的参数验证异常。当你在某个需要 runs 参数的场景中（如 percolator query、watcher condition 或其他支持重复执行的查询）提供了无效的值（如负数、零或超出范围的 … - [a sequence requires a minimum of 2 queries found - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/a-sequence-requires-a-minimum-of-2-queries-found-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.16-8.9+ 1. 错误异常的基本描述 # a sequence requires a minimum of 2 queries; found [value] 是 Elasticsearch 在使用 sequence query（序列查询）时抛出的参数验证错误。当你构造序列查询时，必须在请求中提供至少 2 个查询（查询序列中的每个事件），如果只提供了 1 个或 0 个查询，就 … - [an index exists with the same name as the alias - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/an-index-exists-with-the-same-name-as-the-alias-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.17 1. 错误异常的基本描述 # an index exists with the same name as the alias 是 Elasticsearch 在创建或更新别名（alias）时抛出的 InvalidAliasNameException 异常。该错误的核心含义是：你试图为一个索引创建别名，但该别名与集群中已存在的某个索引名称完全相 … - [could not parse time expected string number value or an object but found - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-time-expected-string-number-value-or-an-object-but-found-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # could not parse time. expected string/number value or an object; but found [token] 是 Elasticsearch Watcher 在解析 time 配置时抛出的异常。此错误表示时间配置的入口 token 既不是单个值（字符串或数字），也不是对象结构，而是 … - [Elasticsearch、OpenSearch、Easysearch 选型决策树指南](https://easysearch.cn/knowledge-base/basic/elasticsearch-opensearch-easysearch-selection-decision-tree/): Elasticsearch（简称ES）、OpenSearch、Easysearch 三款产品均源自 Apache Lucene 技术体系，共享核心搜索内核，但 2021 年成为关键分化节点： ES 7.11 版本起将开源协议从 Apache 2.0 变更为SSPL/ELv2双重授权，转向商业付费导向； OpenSearch 基于 ES 7.10.2（最后一个 Apache 2.0 版本）分叉，坚 … - [Explain FORMAT should be specified at most once - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/explain-format-should-be-specified-at-most-once-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 在 Elasticsearch SQL 的 EXPLAIN 语句里，FORMAT 只能出现一次。解析器会统计 ctx.FORMAT().size()，只要大于 1，就直接抛出这条 ParsingException。 常见现象 # 执行 SQL EXPLAIN 语句时报错，而不是搜索执行阶段失败。 报错通常是即时返回 400。 常见于 … - [Glacier 存储类不受支持 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/glacier-storage-class-is-not-supported-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Glacier storage class is not supported 表示 Elasticsearch 在解析 S3 仓库配置中的 storage_class 时，发现它被设置成了 Glacier，于是直接拒绝该配置。 这是明确的产品限制，不是暂时性故障。原因是快照仓库要求对象可以被及时读取，而 Glacier 属于归档型存储， … - [HTTP TCP 地址重用配置](https://easysearch.cn/knowledge-base/easysearch_config/http.tcp.reuse_address/): 配置项作用 # http.tcp.reuse_address 配置项用于控制是否启用 SO_REUSEADDR socket 选项。 启用此选项允许 socket 绑定到处于 TIME_WAIT 状态的地址，使得服务器在关闭后可以立即重新启动并绑定到同一端口。 配置项属性 # 配置路径: http.tcp.reuse_address 数据类型: Boolean（布尔值） 默认值: … - [MultiLineString 中的行数无效——必须 >= 1——如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/invalid-number-of-lines-in-multilinestring-found-must-be-1-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # MultiLineString 中的行数无效——必须 >= 1— 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现 … - [Setting setting getKey 未为仓库定义 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/setting-setting-getkey-is-not-defined-for-repository-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Setting [xxx] is not defined for repository 表示 Elasticsearch 在读取某个 repository 必需配置时，没有从当前仓库的 settings 中取到值。源码片段里已经很清楚：setting.get(metadata.settings()) 返回 null 时， … - [slice 只能用于 scroll 或 PIT 请求 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/slice-can-only-be-used-with-scroll-or-point-in-time-requests-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.15-8.9 1. 错误异常的基本描述 # 当 Elasticsearch 请求中使用了 slice 参数，但既没有设置 scroll，也没有使用 point-in-time（PIT），集群会拒绝该请求并返回以下错误：[slice] can only be used with [scroll] or [point-in-time] requests。这是服务端在查询解析阶段抛出 … - [Transport TCP 缓冲区大小配置](https://easysearch.cn/knowledge-base/easysearch_config/transport.tcp.buffer_sizes/): 配置项作用 # transport.tcp.receive_buffer_size 和 transport.tcp.send_buffer_size 配置项用于控制TCP 接收和发送缓冲区的大小。 配置项属性 # transport.tcp.receive_buffer_size # 配置路径: transport.tcp.receive_buffer_size 数据类型: … - [TransportService已关闭停止，无法发送请求——如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/transportservice-is-closed-stopped-can-t-send-request-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.5 1. 错误异常的基本描述 # TransportService已关闭停止，无法发送请求— 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能 … - [Wait for seq no refreshed timed out - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/wait-for-seq-no-refreshed-timed-out-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.9-8.9 1. 错误异常的基本描述 # Wait for seq no refreshed timed out 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 … - [不存在远程集群异常 (no_such_remote_cluster_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/no_such_remote_cluster_exception/): 为什么这个错误发生 # no_such_remote_cluster_exception 表示尝试访问不存在的远程集群或无法连接到配置的远程集群。这通常在跨集群查询或跨集群复制时发生。 这个错误可能由以下原因引起： 远程集群未配置：没有配置指定的远程集群 集群别名错误：使用了错误的集群别名 远程集群配置被删除：远程集群配置已被删除或重置 连接失败：无法连接到远程集群的任何节点 远程集群不存在： … - [不能同时使用 collapse 和 rescore - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-use-collapse-in-conjunction-with-rescore-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 当一个搜索请求同时配置了 collapse 和 rescore 时，会收到错误： cannot use `collapse` in conjunction with `rescore` 通常表现为查询直接失败，客户端拿到 search_phase_execution_exception 或相关搜索异常。 2. 为什么会发生这个错误 # … - [分片删除超时配置](https://easysearch.cn/knowledge-base/easysearch_config/indices.store.delete.shard.timeout/): 配置项概述 # indices.store.delete.shard.timeout 配置控制删除分片前检查分片是否可以安全删除的超时时间。此超时适用于检查分片在其他节点上是否活跃的 HTTP 请求。 配置项 默认值 说明 indices.store.delete.shard.timeout 30s 分片删除检查超时 配置说明 # … - [创建快照仓库](https://easysearch.cn/knowledge-base/easysearch_api/create-snapshot-repository/): 此 API 用于创建或更新快照存储仓库。 API # PUT /_snapshot/{repository} POST /_snapshot/{repository} API 的作用 # 创建新的快照存储仓库或更新已存在的仓库配置。快照仓库是存储索引快照的位置，可以是： 共享文件系统：使用共享文件系统存储快照 云存储：使用 S3、Azure、GCS 等云存储服务 其他存储： … - [发布带有汇总元数据的新集群状态失败 – 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-publish-new-cluster-state-with-rollup-metadata-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.11-8.2 1. 错误异常的基本描述 # 发布带有汇总元数据的新集群状态失败 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [响应通道 restRequest getHttpChannel 已关闭 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/response-channel-restrequest-gethttpchannel-closed-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.12-7.13 1. 错误异常的基本描述 # 响应通道 restRequest getHttpChannel 已关闭 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 … - [尝试覆盖ID为taskId的任务 – 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/trying-to-override-task-with-id-taskid-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 尝试覆盖ID为taskId的任务 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [嵌套过滤器已被移除，改用嵌套参数——如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/nested-filter-has-been-removed-in-favour-of-the-nested-parameter-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # 嵌套过滤器已被移除，改用嵌套参数— 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [慢任务日志阈值配置](https://easysearch.cn/knowledge-base/easysearch_config/cluster.service.slow_task_logging_threshold/): 配置项作用 # cluster.service.slow_task_logging_threshold 配置项控制集群管理任务（如集群状态更新、分片分配等）执行时间的日志记录阈值。当任务执行时间超过此阈值时，会记录警告日志，便于识别性能瓶颈。 配置项类型 # 该配置项为动态配置，可以在运行时通过集群设置 API 进行修改。 默认值 # 30s（30秒） 是否必需 # 可选配置项（有默认值） … - [指定的foreach对象为null – 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/specified-foreach-object-was-null-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.3-8.9 1. 错误异常的基本描述 # 指定的foreach对象为null 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [文本分类出现意外的批量输入 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unexpected-batch-input-for-text-classification-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.2-8.9 1. 错误异常的基本描述 # 文本分类出现意外的批量输入 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无效的聚合排序路径 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/invalid-aggregation-order-path-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.6 1. 错误异常的基本描述 # 无效的聚合排序路径 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法为作业 job getId 删除过期的注释 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-remove-expired-annotations-for-job-job-getid-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.15-8.9 1. 错误异常的基本描述 # 无法为作业 job getId 删除过期的注释 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [没有ID为calendarId的日历 – 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/no-calendar-with-id-calendarid-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 没有ID为calendarId的日历 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [生成失败异常 (generation_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/generation_exception/): 为什么这个错误发生 # generation_exception 表示在生成某些内容时失败。这是一个通用的生成异常，通常在客户端库尝试生成请求内容（如 JSON 映射、模板等）时发生。 这个错误可能由以下原因引起： JSON 序列化失败：对象无法序列化为 JSON 格式 映射生成错误：索引映射生成失败 模板生成错误：索引模板生成失败 字段类型不匹配：字段类型与预期不符 循环引用：对象存在循环引 … - [索引刷新间隔配置](https://easysearch.cn/knowledge-base/easysearch_config/config_index.refresh_interval/): 配置项作用 # index.refresh_interval 配置项控制索引的刷新间隔，即新索引的文档何时可以被搜索到。刷新操作将内存中的文档写入 Lucene 段并打开新的搜索器，使新文档对搜索可见。 配置项类型 # 该配置项为动态配置，可以在运行时通过索引设置 API 进行修改。 默认值 # 1s（1秒） 是否必需 # 可选配置项（有默认值） 取值范围 # -1（禁用自动刷新）~ 正 … - [获取待办任务](https://easysearch.cn/knowledge-base/easysearch_api/get-pending-cluster-tasks/): 获取集群中待处理的任务列表，这些任务通常包括需要修改集群状态的操作。 API # GET /_cluster/pending_tasks API 的作用 # 该 API 用于获取集群中待处理的任务列表。它会返回当前在主节点上等待执行的所有集群任务。 待办任务类型 # 待办任务通常包括以下需要修改集群状态的操作： 创建索引 更新设置 分配分片 删除索引 更新映射 其他集群元数据变更 API … - [解析坐标发现 Z 值但 ignore_z_value 未设置 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/exception-parsing-coordinates-found-z-value-but-ignore-z-value-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.11-7.15 1. 错误异常的基本描述 # 解析坐标发现 Z 值但 ignore_z_value 未设置 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [解析坐标异常 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/exception-parsing-coordinates-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # 解析坐标异常 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [解析对象失败：空键 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-object-empty-key-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 解析对象失败：空键 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [解析词向量请求失败 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-term-vectors-request-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # failed to parse term vectors request 表示 Elasticsearch 在解析 _termvectors 接口请求体时遇到格式或结构错误，无法将传入的 JSON 解析为合法的 Term Vectors 请求对象。该异常通常在 DSL 解析阶段直接抛出，请求尚未进入执行流程。 常见现象 # … - [跟随索引没有分片跟随任务 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/no-shard-follow-tasks-for-follower-indices-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 跟随索引没有分片跟随任务 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Easysearch 里的索引、文档，到底像不像数据库表？一场深度辨析](https://easysearch.cn/knowledge-base/basic/easysearch-indexes-and-documents-are-they-like-database-tables/): 许多开发者初次接触 Easysearch 时，都会被其 Index、Document、Field 这些概念与数据库中 Table、Row、Column 的高度相似性所吸引。这种熟悉感像一座桥梁，大大降低了学习门槛，让开发者能快速上手。 但这种“相似”是福是祸？它是否会让我们在不经意间，将 Easysearch 当成一个“超强数据库”来误用，从而导致各种性能问题或架构上的误解？ 本文将通过深度对比， … - [failed to load SSL configuration - SSL 配置加载失败](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-load-ssl-configuration-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.4-8.9 1. 错误异常的基本描述 # failed to load SSL configuration [{}] - {} 来自安全配置加载流程。源码会对每个 SSL 配置键调用 SslSettingsLoader.load(...)，一旦抛出 SslConfigException，就会把具体配置键与底层错误信息一起拼到异常里。 这不是模糊错误，因为日志里已经给出了具体配置 … - [Fetch Shard Store 线程池最大大小配置](https://easysearch.cn/knowledge-base/easysearch_config/thread_pool.fetch_shard_store.max/): 配置项作用 # thread_pool.fetch_shard_store.max 配置项用于控制分片存储元数据获取线程池的最大线程数。 这是线程池能够创建的最大线程数量上限。 配置项属性 # 配置路径: thread_pool.fetch_shard_store.max 数据类型: Integer（整数） 默认值: 2 × CPU核心数（受限于 2 到 Integer.MAX_VALUE） … - [ILM 作业执行间隔配置](https://easysearch.cn/knowledge-base/easysearch_config/index_lifecycle_management.job_interval/): 配置项作用 # index_lifecycle_management.job_interval 配置项用于控制索引生命周期管理（ILM）调度器检查并执行生命周期任务的频率。 ILM 是 Easysearch 中用于自动管理索引生命周期的功能，可以自动执行索引的滚动（rollover）、收缩（shrink）、删除（delete）等操作。 配置项属性 # 配置路径: … - [Pattern must not be null – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/pattern-must-not-be-null-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.6-8.9 1. 错误异常的基本描述 # Pattern must not be null 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Properties 必须是 map 类型 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/properties-must-be-a-map-type-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Properties 必须是 map 类型 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [QueryName 查询格式错误：查询名称后缺少起始对象 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/queryname-query-malformed-no-start-object-after-query-name-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # QueryName 查询格式错误：查询名称后缺少起始对象 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口 … - [Span containing little must be of type span query – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/span-containing-little-must-be-of-type-span-query-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Span containing little must be of type span query 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与 … - [Transform任务未完全初始化，请稍后重试——如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/task-for-transform-not-fully-initialized-try-again-later-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.2-7.3 1. 错误异常的基本描述 # Transform任务未完全初始化，请稍后重试— 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Unknown month - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unknown-month-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误说明 # unknown month 是 Elasticsearch 在解析日期、时间表达式或 Watcher 调度配置时抛出的 ElasticsearchParseException。当输入的月份值无法被识别为合法的月份名称或数字时，Elasticsearch 会抛出此异常并中断当前操作。 该错误最常见于以下场景： Watcher 定时任务配置： … - [Value cannot be used as it is too large to convert into s - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/value-cannot-be-used-as-it-is-too-large-to-convert-into-s-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Value cannot be used as it is too large to convert into s 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日 … - [令牌失效失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-invalidate-token-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.7-8.9 1. 错误异常的基本描述 # 令牌失效失败 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返回 400、404、409、429、500 … - [发布在提交前被取消 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/publication-cancelled-before-committing-how-to-solve-this-elasticsearch-exception/): 适用版本： 7-8.9 1. 错误异常的基本描述 # 发布在提交前被取消 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [启动 Rollup 任务失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-start-rollup-task-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.11-8.9 1. 错误说明 # failed to start rollup task 表示 Elasticsearch 在尝试启动 Rollup 任务时，内部的 indexer.start() 方法未能返回 IndexerState.STARTED 状态，导致任务启动流程被中断并抛出异常。 Rollup 是 Elasticsearch 提供的一种历史数据降采样机制，用于将高 … - [字段 name 的属性值不能为 null - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/property-value-of-field-name-can-t-be-null-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.7-7.9 1. 错误异常的基本描述 # 字段 name 的属性值不能为 null 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [引擎异常 (engine_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/engine_exception/): 为什么这个错误发生 # engine_exception 是 Lucene 引擎层面的通用异常。引擎负责索引的读写操作，当底层操作失败时会抛出此异常。 这个错误可能由以下原因引起： 索引损坏：Lucene 索引文件损坏 写入冲突：并发写入操作冲突 磁盘空间不足：磁盘空间不足导致写入失败 文件锁定：索引文件被锁定无法访问 内存不足：JVM 堆内存不足 段合并失败：段合并过程中发生错误 事务日志问 … - [无效的别名过滤器 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/invalid-alias-filter-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 无效的别名过滤器 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法打开 Job - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-open-job-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.10 1. 错误说明 # Cannot open job [job_id] because it has already been opened 表示指定的机器学习作业（ML Job）已经处于打开状态，此时再次调用 open job API 会触发状态冲突异常。该异常在 Elasticsearch … - [无法检索数据因为索引不存在 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-retrieve-data-because-index-indexnotfoundexception-e-getindex-does-not-exist-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.4 1. 错误异常的基本描述 # 无法检索数据因为索引不存在 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [映射异常 (mapper_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/mapper_exception/): 为什么这个错误发生 # mapper_exception 表示与索引映射（mapping）相关的错误。映射定义了文档的字段类型和属性，当操作与映射定义冲突时就会抛出此异常。 这个错误可能由以下原因引起： 字段类型冲突：尝试索引与字段映射类型不匹配的数据 映射定义错误：映射定义的语法或结构不正确 动态映射冲突：自动检测的类型与现有类型冲突 对象嵌套过深：对象嵌套层级超过限制 字段数量超限：索引字 … - [构建时检测到未使用的参数 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unused-parameters-detected-when-building-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.12-7.15 1. 错误异常的基本描述 # 构建时检测到未使用的参数 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [查询文档数量（Cat格式）](https://easysearch.cn/knowledge-base/easysearch_api/get-doc-count-cat-format/): 以紧凑的表格形式返回索引的文档数量。 API 格式 # GET /_cat/count GET /_cat/count/{index} API 作用 # 该 API 以表格形式返回索引的文档数量： 显示所有索引或指定索引的文档总数 支持查询过滤 快速查看文档统计 API 参数 # 路径参数 # 参数 类型 是否必填 默认值 描述 {index} String … - [纬度必须是数值——如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/latitude-must-be-a-numeric-value-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 纬度必须是数值— 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [脚本最大大小配置](https://easysearch.cn/knowledge-base/easysearch_config/script.max_size_in_bytes/): 配置项作用 # script.max_size_in_bytes 配置项限制脚本源代码的最大大小（字节），包括内联脚本和存储脚本。 是否可选 # 是 默认值 # 65535 (64KB) 配置项类型 # 动态配置 - 可以在运行时修改 配置格式 # # 默认配置 script.max_size_in_bytes: 65535 # … - [自动跟随模式缺失 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/auto-follow-pattern-is-missing-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 自动跟随模式缺失 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [节点失败 discoveryNode getId – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-node-discoverynode-getid-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.9-8.9 1. 错误异常的基本描述 # 节点失败 discoveryNode getId 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [获取热点线程](https://easysearch.cn/knowledge-base/easysearch_api/get-hot-threads/): 获取集群中各个节点的热点线程信息，用于监控和分析 JVM 中线程的活动情况，帮助定位性能问题和瓶颈。 注意：该 API 已被标记为弃用（deprecated），推荐使用 /_nodes/hot_threads 替代。 API # GET /_cluster/nodes/hot_threads GET /_cluster/nodes/{nodeId}/hot_threads API 的作用 # … - [设置必须是某值的倍数 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/setting-must-be-multiple-of-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.12-8.9 1. 错误异常的基本描述 # 设置必须是某值的倍数 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [设置覆盖值格式错误 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/malformed-setting-override-value-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.2-8.9 1. 错误异常的基本描述 # Malformed setting override value 是 Elasticsearch 在启动阶段或动态加载配置时抛出的 SettingsException 异常。当 Elasticsearch 尝试将一段设置覆盖（override）内容解析为 YAML 格式并加载为内部 Settings 对象时，如果解析失败，就会触发该错 … - [跟随节点延迟超时配置](https://easysearch.cn/knowledge-base/easysearch_config/cluster.follower_lag.timeout/): 配置项作用 # cluster.follower_lag.timeout 配置项控制跟随节点（Follower Node）应用集群状态更新的超时时间。当主节点（Leader Node）发布了新的集群状态后，如果跟随节点在指定的时间内没有成功应用该状态，系统可能会将其从集群中移除，以防止集群长期处于不一致状态。 配置项类型 # 该配置项为静态配置，需要在启动时设置，修改后需要重启节点才能生效。 … - [集群发现配置: initial_state_timeout](https://easysearch.cn/knowledge-base/easysearch_config/discovery.initial_state_timeout/): discovery.initial_state_timeout 配置项控制集群发现相关行为。 配置格式 # # 默认配置 discovery.initial_state_timeout: default - [集群状态尚未恢复，无法写入安全索引 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cluster-state-has-not-been-recovered-yet-cannot-write-to-the-security-index-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.1 1. 错误异常的基本描述 # 集群状态尚未恢复，无法写入安全索引 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [a single subject must have either a single result or error - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/a-single-subject-must-have-either-a-single-result-or-error-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11+ 1. 错误异常的基本描述 # a single subject must have either a single result or error 是 Elasticsearch 的 ProfileService（性能分析服务）抛出的内部一致性错误。当你使用搜索性能分析（_search?profile=true）或索引性能分析功能时，如果内部主 … - [Datafeed 无法取数，因为索引不存在 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/datafeed-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # 这个异常说明 datafeed 在尝试读取训练或分析数据时，目标索引不存在。源码会把底层的 IndexNotFoundException 转成一个更明确的资源不存在错误。 典型报错： datafeed [datafeed_id] cannot retrieve data because index [index_name] does … - [Easysearch 分布式架构核心设计详解](https://easysearch.cn/knowledge-base/basic/easysearch-distributed-architecture-design/): 在构建企业级搜索平台时，我们不仅关注“快”，更关注“准”和“稳”。Easysearch 作为一个分布式的 Near Real-Time（近实时）搜索引擎，其核心架构设计解决的最根本问题是：在不可靠的网络和硬件之上，构建一个可靠的数据系统。 本文将深入剖析 Easysearch 分布式架构的三大基石：集群协调模型、数据复制模型以及并发控制机制。 一、 集群协调：去中心化与共识算法 # … - [Flush 线程池保活时间配置](https://easysearch.cn/knowledge-base/easysearch_config/thread_pool.flush.keep_alive/): 配置项作用 # thread_pool.flush.keep_alive 配置项用于控制索引刷新线程池中弹性线程的保活时间。 当线程数超过核心线程数时，空闲的弹性线程在指定时间后会被回收。 配置项属性 # 配置路径: thread_pool.flush.keep_alive 数据类型: TimeValue（时间值） 默认值: 5m（5 分钟） 是否可选: 是 作用域: NodeScope（节 … - [http request 某个字段解析失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-http-request-could-not-parse-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # could not parse http request. could not parse [field] field 表示 Elasticsearch 在解析 Watcher 中定义的 HTTP request 动作时，某个指定字段无法被正确解析。该错误是 Watcher 内部解析器的包装异常，真正的问题发生在具体子字段（ … - [Points only 不能为 term 策略设置为 false – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/points-only-cannot-be-set-to-false-for-term-strategy-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.1 1. 错误异常的基本描述 # Points only 不能为 term 策略设置为 false 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Slack 账户配置中的 URL 设置无效 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/invalid-slack-name-account-settings-invalid-url-setting-setting-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # 这个错误说明 Slack account 虽然配置了 URL，但该值无法被 URI 正常解析。也就是说，问题不在 Slack message 内容，而在账户级 webhook 地址本身格式非法。 典型报错： invalid slack [alerts] account settings. invalid [url] setting … - [Unable to find index in cluster state - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unable-to-find-index-in-cluster-state-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.6-8.9 1. 错误异常的基本描述 # Unable to find index in cluster state 表示 Elasticsearch 在集群状态（cluster state）的元数据中无法找到指定的索引。该异常通常在执行分片级别操作（如读取、写入、恢复、relocate 等）时触发，当集群状态中根据索引名称查找 IndexMetadata 返回 null 时抛 … - [URL 仓库允许地址配置](https://easysearch.cn/knowledge-base/easysearch_config/repositories.url.allowed_urls/): 配置项作用 # repositories.url.allowed_urls 配置项用于控制URL 仓库可以访问的地址白名单。 当使用 URL 类型的快照仓库时，此配置提供了一个安全机制，限制仓库只能访问指定的 URL 模式，防止未经授权的 URL 访问。 配置项属性 # 配置路径: repositories.url.allowed_urls 数据类型: … - [不支持的聚合类型 agg getType](https://easysearch.cn/knowledge-base/elasticsearch_error/unsupported-aggregation-type-agg-gettype-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.4-7.1 1. 错误异常的基本描述 # 不支持的聚合类型 agg getType 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [任务缺失 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/task-is-missing-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 任务缺失 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返回 400、404、409、429、500 … - [分片未启动 (index_shard_not_started_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/index_shard_not_started_exception/): 为什么这个错误发生 # index_shard_not_started_exception 表示分片尚未启动，无法执行请求的操作。分片需要经过初始化过程后才能正常处理请求。 这个错误可能由以下原因引起： 分片正在初始化：分片刚刚被创建或分配，正在初始化过程中 分片正在恢复：分片正在从其他节点恢复数据 分片正在迁移：分片正在从一个节点迁移到另一个节点 分片被关闭：分片被关闭后尚未重新打开 引擎未 … - [分片级限流令牌补充间隔配置](https://easysearch.cn/knowledge-base/easysearch_config/cluster.throttle.shard.write.interval/): 配置项作用 # 设置分片级限流令牌桶的令牌补充间隔时间（秒）。 默认值 # 1 配置格式 # # 每秒补充一次令牌（默认） cluster.throttle.shard.write.interval: 1 # 每 2 秒补充一次 cluster.throttle.shard.write.interval: 2 - [图顶点定义中的非法属性 – 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/illegal-property-in-graph-vertices-definition-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # 图顶点定义中的非法属性 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [在描述符中找不到指定项 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-find-in-descriptor-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # 在描述符中找不到指定项 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [存储被并发关闭 – 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/store-got-closed-concurrently-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.9-8.9 1. 错误异常的基本描述 # 存储被并发关闭 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [尝试启动失败的转换任务 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/attempted-to-start-a-failed-transform-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.4-8.9 1. 错误异常的基本描述 # Attempted to start a failed transform 表示尝试启动一个已经处于 FAILED 状态的 Transform 任务。Elasticsearch 的 Transform 任务在运行失败后会进入 failed 状态，此时不允许直接再次启动，必须先处理失败原因并将任务重置为可启动状态，否则会抛出此异常。 常见 … - [快照创建失败 (snapshot_creation_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/snapshot_creation_exception/): 为什么这个错误发生 # snapshot_creation_exception 表示创建快照操作完全失败。这与单个分片快照失败不同，这是整个快照创建过程的失败。 这个错误可能由以下原因引起： 仓库配置错误：快照仓库配置不正确或无法访问 权限问题：没有访问仓库的权限 存储空间不足：仓库存储空间不足 网络问题：无法连接到远程仓库 索引状态异常：索引处于关闭或不可用状态 并发快照冲突：同时创建多个快 … - [恢复快照](https://easysearch.cn/knowledge-base/easysearch_api/restore-snapshot/): 此 API 用于从快照恢复数据到集群。 API # POST /_snapshot/{repository}/{snapshot}/_restore API 的作用 # 从指定的快照中恢复数据到集群。恢复操作可以： 恢复全部索引：恢复快照中的所有索引 恢复部分索引：只恢复指定的索引 重命名索引：恢复时重命名索引 修改设置：恢复时修改索引设置 全局状态：恢复全局集群状态 API 的参数 # … - [握手失败，意外的远程节点 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/handshake-failed-unexpected-remote-node-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 握手失败，意外的远程节点 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无效的条件格式必须为 condition=value – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/invalid-condition-format-must-be-conditionvalue-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # 无效的条件格式必须为 condition=value 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可 … - [无法对 POINT 类型进行四舍五入 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/can-t-round-a-point-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.17-8.9 1. 错误异常的基本描述 # can't round a [POINT] 是 Elasticsearch 在执行聚合（Aggregation）阶段抛出的 AggregationExecutionException。该异常的核心含义是：当前聚合器试图对 POINT 类型的字段值执行四舍五入（rounding）操作，但该操作对点数据类型不适用。 … - [无法获取字段能力 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-fetch-field-caps-for-how-to-solve-this-elasticsearch-exception/): 适用版本： 8-8.7 1. 错误异常的基本描述 # 无法获取字段能力 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法解析 Watch，遇到空 token - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-watch-null-token-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.x 1. 错误异常的基本描述 # could not parse watch [<id>]. null token 表示 Watch 解析器在还没有正常读到对象结束标记前，就拿到了 null token。 这通常说明 Elasticsearch 读到的内容不是一个完整、合法的 Watch JSON。最常见的情况不是字段值错误，而是 请求体为空、内容被截断，或 … - [无法解析SAML内容 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-unmarshall-saml-content-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.7-8.9 1. 错误异常的基本描述 # 无法解析SAML内容 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法解析字段，期望字符串数组但数组中某个值不匹配 (expected a string array but one of the value in the) - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-field-expected-a-string-array-but-one-of-the-value-in-the-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # 无法解析字段，期望字符串数组但数组中某个值不匹配 (expected a string array but one of the value in the) 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳 … - [无法解析监视的转换，解析失败 (Could not parse transform for watch failed to parse) - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-transform-for-watch-failed-to-parse-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # 无法解析监视的转换，解析失败 (Could not parse transform for watch failed to parse) 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报 … - [无法识别类型 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/does-not-recognize-type-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 无法识别类型 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [模拟索引模板](https://easysearch.cn/knowledge-base/easysearch_api/simulate-index-template/): 模拟索引模板匹配，验证特定索引名称会应用哪些模板配置。 API # POST /_index_template/{name}/_simulate POST /_template/{name}/_simulate POST /_template/_simulate API 的作用 # 该 API 用于模拟索引模板的匹配和应用，帮助您： … - [生成映射源失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-generate-mappingsource-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 生成映射源失败 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [系统写入线程池配置](https://easysearch.cn/knowledge-base/easysearch_config/thread_pool.system_write/): 配置项作用 # thread_pool.system_write 相关配置项控制用于执行系统级别写入操作的线程池。系统写入操作包括集群状态更新、元数据修改等内部系统管理操作。该线程池采用固定大小线程池类型。 配置项类型 # 该配置项为静态配置，需要在启动时设置，修改后需要重启节点才能生效。 默认值 # thread_pool.system_write.size: … - [节点 ID 种子配置](https://easysearch.cn/knowledge-base/easysearch_config/node.id.seed/): 配置项作用 # node.id.seed 配置项用于控制生成节点唯一标识符（UUID）时的随机种子值。 此配置作为生成节点 ID 的种子，用于确定节点的持久化 UUID。如果磁盘上已经存在持久化的 UUID，则此配置会被忽略，重用已有的 UUID。 配置项属性 # 配置路径: node.id.seed 数据类型: Long（长整型） 默认值: 0L 最小值: Long.MIN_VALUE 最 … - [解析 Watch Input 时出现未预期 token - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-input-for-watch-unexpected-token-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # could not parse [TYPE] input for watch [watchId]. unexpected token [token] 表示 Elasticsearch 在解析某个特定类型的 Watch Input 时，遇到了当前解析上下文无法接受的 token 类型。 该错误属于 Watcher 模块的解析异 … - [预期出现右括号但发现其他内容 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/expected-rparen-but-found-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 预期出现右括号但发现其他内容 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Action [action] not found - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/action-action-not-found-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9+ 1. 错误异常的基本描述 # Action [action] not found 是 Elasticsearch 的**传输服务（Transport Service）**抛出的异常。当你向 Elasticsearch 发送一个不存在的 action（操作类型）请求时，就会触发此错误。每个 Elasticsearch API 都有一个对应的 action 名称（ … - [could not parse time time format must be in the form of hh mm - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-time-time-format-must-be-in-the-form-of-hh-mm-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # could not parse time [value]. time format must be in the form of hh:mm 是 Elasticsearch 在解析时间字符串时抛出的异常。此错误表示时间字符串的整体形态不符合解析器要求的 hh:mm 格式。 此错误发生在 hour/minute 具体值校验之前，属于时间 … - [expected object but found instead - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/expected-object-but-found-instead-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # expected object but found {} instead 表示 Elasticsearch 在解析请求体（JSON）时，当前位置期望遇到一个 JSON 对象（START_OBJECT），但实际读到的 token 类型不匹配。这是一类请求体结构错误，发生在解析阶段，而非运行期执行阶段。 常见变体包括： expected … - [Expected XContentParser Token START ARRAY in – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/expected-xcontentparser-token-start-array-in-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # Expected XContentParser Token START ARRAY in 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起 … - [UUID 长度必须为正数——如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/uuid-length-must-be-positive-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # UUID 长度必须为正数— 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [不支持序列分支——如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/sequence-fork-is-unsupported-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.8-7.9 1. 错误异常的基本描述 # 不支持序列分支— 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [主节点故障检测超时配置](https://easysearch.cn/knowledge-base/easysearch_config/cluster.fault_detection.leader_check.timeout/): 配置项作用 # cluster.fault_detection.leader_check.timeout 配置项控制从节点向主节点发送健康检查请求后的等待响应超时时间。如果在指定时间内未收到响应，则认为本次检查失败。连续多次失败后会判定主节点故障，触发重新选举。 配置项类型 # 该配置项为静态配置，需要在启动时设置，修改后需要重启节点才能生效。 默认值 # 10s 是否必需 # 可选配置 … - [主节点重试异常 (retry_on_primary_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/retry_on_primary_exception/): 为什么这个错误发生 # retry_on_primary_exception 表示在主分片上执行的操作失败，需要在主分片上重试。这个异常通常在主分片状态发生变化时发生。 这个错误可能由以下原因引起： 主分片已迁移：操作执行时主分片已迁移到其他节点 主分片不再是主：原主分片降级为副本，新的主分片已选出 主分片恢复中：主分片正在恢复过程中，暂时无法处理写操作 并发版本冲突：存在并发操作导致主分片变 … - [分布式架构如何支撑海量数据？Easysearch 集群工作原理图解](https://easysearch.cn/knowledge-base/basic/distributed-architecture-cluster-work-principle/): 在之前的文章中，我们已经见识了 Easysearch 在开发和运维上的便捷。但当数据量从 GB 增长到 TB 甚至 PB 级别时，一个根本性的问题摆在了我们面前：单台服务器的物理极限，如何被打破？ 这正是“分布式”大显身手的舞台。Easysearch 天生就是一个分布式系统，它的强大并非源于单个节点的“蛮力”，而是其背后一套优雅、高效的集群协作机制。 今天，让我们用一个“创业公司”的比喻，来为你图 … - [删除存储脚本](https://easysearch.cn/knowledge-base/easysearch_api/delete-stored-script/): 从集群中删除指定的存储脚本。 API 格式 # DELETE /_scripts/{id} API 作用 # 该 API 用于从集群中删除存储脚本： 删除指定 ID 的存储脚本 删除后无法在查询、更新等操作中使用该脚本 操作是异步的，立即返回确认响应 API 参数 # 路径参数 # 参数 类型 是否必填 默认值 描述 {id} String 是 - 要删除的存储脚本 ID … - [在 Watcher 中解析输入后期望 JSON 对象闭合 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/expected-closing-json-object-after-parsing-input-named-in-watch-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # 在 Watcher 中解析输入后期望 JSON 对象闭合 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接 … - [字段名不能设置 doc_values = false – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/the-field-name-cannot-have-doc-values-false-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.9-7.1 1. 错误异常的基本描述 # 字段名不能设置 doc_values = false 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能 … - [字段掩码span必须包含query span查询子句 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/field-masking-span-must-have-query-span-query-clause-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.14 1. 错误异常的基本描述 # 字段掩码span必须包含query span查询子句 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可 … - [必需的别名不存在 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/required-alias-alias-does-not-exist-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.11-8.9 1. 错误异常的基本描述 # 必需的别名不存在 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [持久化任务重新检查间隔配置](https://easysearch.cn/knowledge-base/easysearch_config/cluster.persistent_tasks.allocation.recheck_interval/): 配置项作用 # cluster.persistent_tasks.allocation.recheck_interval 配置项控制主节点重新检查未分配持久化任务的时间间隔。当持久化任务无法立即分配到节点时（如节点资源不足、节点不满足条件等），系统会定期重新尝试分配这些任务。 配置项类型 # 该配置项为动态配置，可以在运行时通过集群设置 API 进行修改。 默认值 # 30s 是否必需 # … - [操作超时 (timeout_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/timeout_exception/): 为什么这个错误发生 # timeout_exception 表示操作执行时间超过了预设的超时限制。这是一个通用的超时异常，可能发生在各种操作中。 这个错误可能由以下原因引起： 操作执行时间过长：查询、索引、批量操作等执行时间超过超时设置 集群资源不足：CPU、内存或磁盘 I/O 不足导致操作缓慢 网络延迟：节点间网络通信延迟高 锁竞争：多个操作竞争同一资源导致等待 分片未分配：操作等待分片分配 … - [数据帧转换任务请求 getId 未找到 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/task-for-data-frame-transform-request-getid-not-found-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.2-7.4 1. 错误异常的基本描述 # 数据帧转换任务请求 getId 未找到 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无效的时间分钟值 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/invalid-time-minute-value-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 无效的时间分钟值 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法为发布到节点序列化集群状态差异 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-serialize-cluster-state-diff-for-publishing-to-node-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.16-8.9 1. 错误异常的基本描述 # 无法为发布到节点序列化集群状态差异 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法在复合聚合 [name] 中设置after键 – – 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-set-after-key-in-the-composite-aggregation-name-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.13-7.15 1. 错误异常的基本描述 # 无法在复合聚合 [name] 中设置after键 – 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口 … - [无法验证经纬度值 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/couldn-t-validate-latitude-longitude-values-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # 无法验证经纬度值 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [最大索引缓冲区大小配置](https://easysearch.cn/knowledge-base/easysearch_config/indices.memory.max_index_buffer_size/): 配置项作用 # indices.memory.max_index_buffer_size 配置项控制每个分片的最大索引缓冲区大小。当根据总缓冲区和分片数计算的分配值超过此限制时，将使用此最大值而不是计算值。 配置项类型 # 该配置项为静态配置，需要在启动时设置，修改后需要重启节点才能生效。 默认值 # -1（无限制） 是否必需 # 可选配置项（有默认值） 取值范围 # -1 ~ 正无 … - [查询安全用户](https://easysearch.cn/knowledge-base/easysearch_api/get-security-user/): 此 API 用于获取 Easysearch 安全模块中的内部用户配置信息。 API # GET /_security/user GET /_security/user/{name} API 的作用 # 查询内部用户（internal users）的配置信息。可以： 获取所有用户：返回所有用户配置 获取指定用户：返回特定用户的配置信息 批量查询：通过参数查询多个用户 用户信息包括角色、属性 … - [每节点批量操作连接数配置](https://easysearch.cn/knowledge-base/easysearch_config/transport.connections_per_node.bulk/): 配置项作用 # transport.connections_per_node.bulk 配置项控制集群中每个节点之间用于批量操作（Bulk Operations）的并发连接数。批量操作包括批量索引（Bulk Indexing）、批量更新等大数据量写入操作。增加此值可以提高批量写入吞吐量，但也会消耗更多资源。 配置项类型 # 该配置项为静态配置，需要在启动时设置，修改后需要重启节点才能生效。 默 … - [磁盘阈值重路由间隔配置](https://easysearch.cn/knowledge-base/easysearch_config/cluster.routing.allocation.disk.reroute_interval/): 配置项作用 # cluster.routing.allocation.disk.reroute_interval 配置项用于控制磁盘阈值监控器触发重路由（reroute）操作的最小间隔时间。 当节点磁盘使用率超过高水位线或从低水位线恢复时，系统会触发分片重路由。此配置确保重路由操作不会过于频繁，避免系统不稳定。 配置项属性 # 配置路径: … - [节点失败 node getId - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-node-node-getid-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.7-8.9 1. 错误异常的基本描述 # 节点失败 node getId 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [节点正在关闭 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/node-is-shutting-down-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.11-8.9 1. 错误异常的基本描述 # 节点正在关闭 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [解析源设置时出现意外的 token - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unexpected-token-while-parsing-source-settings-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 解析源设置时出现意外的 token 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [请求内容构建失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-request-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # failed to parse request 是 Elasticsearch 在内部处理请求时抛出的异常，表示在将请求对象重新构建为 XContent 格式的过程中发生了失败。与普通的 JSON 解析错误不同，这个异常通常发生在请求已经被接收、但在内部转换或重写阶段出了问题。 常见现象 # 接口返回 500 或 400 状态码，异 … - [还原过程中无法删除快照 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-delete-snapshot-during-a-restore-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.5 1. 错误异常的基本描述 # cannot delete snapshot during a restore 表示当前集群仍有 restore 任务正在使用这个快照或正在执行任意 restore 流程，Elasticsearch 为避免恢复过程依赖的文件被提前删除，直接抛出 ConcurrentSnapshotExecutionException 阻止删除。 这是一 … - [集群 clusterAlias 缺少许可证信息 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/license-info-is-missing-for-cluster-clusteralias-get-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 集群 clusterAlias 缺少许可证信息 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [ISM 历史索引最大年龄配置](https://easysearch.cn/knowledge-base/easysearch_config/index_state_management.history.max_age/): 配置项作用 # index_state_management.history.max_age 配置项用于控制ISM 历史索引触发滚动操作前的最大存活时间。 当历史索引的年龄达到此配置值时，系统会自动创建新的历史索引并将写入别名指向新索引。 配置项属性 # 配置路径: index_state_management.history.max_age 数据类型: TimeValue（时间值） 默认 … - [Profile uid differentiator 不是数字——如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/profile-uid-differentiator-is-not-a-number-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.2-8.9 1. 错误异常的基本描述 # Profile uid differentiator 不是数字— 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Sampler聚合必须与子聚合一起使用 – 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/sampler-aggregation-must-be-used-with-child-aggregations-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Sampler聚合必须与子聚合一起使用 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Span within must include little - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/span-within-must-include-little-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Span within must include little 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Translog header truncated – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/translog-header-truncated-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Translog header truncated 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可 … - [Transport Tracer 包含配置](https://easysearch.cn/knowledge-base/easysearch_config/transport.tracer.include/): 配置项作用 # transport.tracer.include 配置项用于指定哪些传输层操作应该包含在追踪日志中。 配置项属性 # 配置路径: transport.tracer.include 数据类型: List<String>（字符串列表） 默认值: 空列表（不追踪特定操作） 是否可选: 是 作用域: NodeScope（节点级别） 动态更新: 是（可以动态更新，无需重启） … - [从源节点接收到集群状态但当前正在跟随其他节点 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/received-cluster-state-from-sourcenode-but-currently-following-how-to-solve-this-elasticsearch-exception/): 适用版本： 7-7.15 1. 错误异常的基本描述 # 从源节点接收到集群状态但当前正在跟随其他节点 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [任务被取消 (task_cancelled_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/task_cancelled_exception/): 为什么这个错误发生 # task_cancelled_exception 表示正在执行的任务被任务管理 API 或系统主动取消。 这个错误可能由以下原因引起： 手动取消：通过任务管理 API 手动取消任务 节点关闭：节点正在关闭，正在执行的任务被取消 超时取消：任务执行时间超过超时限制 资源限制：系统资源不足导致任务被取消 集群状态变更：集群状态变更导致任务失效 索引删除： … - [使用 PBKDF2 进行密码哈希时出错 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/error-using-pbkdf2-for-password-hashing-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.11-8.9 1. 错误异常的基本描述 # 使用 PBKDF2 进行密码哈希时出错 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [删除索引别名](https://easysearch.cn/knowledge-base/easysearch_api/delete-index-alias/): 从索引中删除别名，释放别名名称或更新索引-别名映射关系。 API # DELETE /{index}/_alias/{name} DELETE /{index}/_alias/{name} DELETE /{index}/_alias/{name} DELETE /_alias/{name} DELETE /_alias/{name} API 的作用 # 从索引中删除别名，移除别名与索引的关联 … - [国产搜索数据库选型指南：Easysearch vs 拓尔思海贝](https://easysearch.cn/knowledge-base/basic/easysearch-vs-trs-hybase-selection-guide/): 前言：国产搜索数据库的崛起与跨越 # 在数字化转型和信息技术创新（信创）持续推进的背景下，企业对底层基础设施的要求正在发生显著变化。“是否自主可控”“是否可长期演进”“是否适合私有化部署”，逐渐成为搜索系统选型时绕不开的问题。 作为数据访问与信息检索的核心引擎，搜索技术本身也正在从“单一功能组件”，演进为企业级数据平台的重要底座。在这一过程中，国产搜索产品不再仅仅承担“替代角色”，而是开始形成清 … - [在字段名称上执行脚本时出错 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/error-executing-script-on-field-name-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.13-8.9 1. 错误异常的基本描述 # 在字段名称上执行脚本时出错 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [字段名称尝试覆盖时间序列维度 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/field-name-attempted-to-shadow-a-time-series-dimension-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.0-8.9 1. 错误异常的基本描述 # Field [xxx] attempted to shadow a time_series_dimension 是 Elasticsearch 时间序列索引（time series index）中特有的映射异常。当索引中某个字段的名称与已定义的**时间序列维度字段（time_series_dimension）**同名，但字段类型或用途不 … - [尝试对失败的转换执行搜索请求 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/attempted-to-do-a-search-request-for-failed-transform-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.4-8.9 1. 错误异常的基本描述 # Attempted to do a search request for failed transform [<transform_id>] 是 Elasticsearch Transform 功能在特定状态下抛出的运行时异常。当某个 Transform 任务已经处于 FAILED 状态，而系统内部或客户端仍尝试对该任务执行 … - [快照不存在——如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/snapshot-does-not-exist-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # snapshot does not exist 表示 Elasticsearch 已经成功读取到仓库 RepositoryData，但在 getSnapshotIds() 中找不到用户请求的 snapshotName，于是直接抛出 SnapshotRestoreException。这类问题发生在 restore、snapshot … - [快照无法读取 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/snapshot-could-not-be-read-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Snapshot could not be read 表示 Elasticsearch 在读取某个快照整体元数据时出现异常，且该异常不是更具体的 failed to get snapshot info 之类已知分支，于是被统一包装成 SnapshotException。从源码看， … - [持久化任务分配开关配置](https://easysearch.cn/knowledge-base/easysearch_config/cluster.persistent_tasks.allocation.enable/): 配置项作用 # cluster.persistent_tasks.allocation.enable 配置项控制是否允许持久化任务（Persistent Tasks）分配到集群节点。持久化任务是指在集群状态中维护的长期运行任务，如机器学习作业、滚动升级任务等。 配置项类型 # 该配置项为动态配置，可以在运行时通过集群设置 API 进行修改。 默认值 # all（允许所有持久化任务分配） 是否 … - [文件长度缺失或无效 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/missing-or-invalid-file-length-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 文件长度缺失或无效 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [文本分类结果无数据 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/text-classification-result-has-no-data-how-to-solve-this-elasticsearch-exception/): 适用版本： 8-8.9 1. 错误异常的基本描述 # 文本分类结果无数据 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [文档解析错误 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/error-parsing-document-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.8-8.9 1. 错误异常的基本描述 # 文档解析错误 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无效的 LinearRing 发现坐标未闭合 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/invalid-linearring-found-coordinates-are-not-closed-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 无效的 LinearRing 发现坐标未闭合 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法向 CoordinateBuilder 添加坐标 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unable-to-add-coordinate-to-coordinatebuilder-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # 无法向 CoordinateBuilder 添加坐标 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可 … - [无法找到请求的资源 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-find-requested-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 无法找到请求的资源 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法找到默认账户 defaultAccountName – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-find-default-account-defaultaccountname-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 无法找到默认账户 defaultAccountName 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可 … - [无法解析监视器状态，期望字段保存 Long 值（Could not parse watch status. expecting field to hold a long value）- 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-watch-status-expecting-field-to-hold-a-long-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.x 1. 错误异常的基本描述 # could not parse watch status. expecting field [...] to hold a long value; found [...] instead 表示 Watcher 期望某个状态字段是 long 整数，但实际拿到的 token 不是可读取的数值。 常见字段之一是 version。这类字段必须是 … - [无法运行预测：内部错误，请检查日志 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-run-forecast-internal-error-please-check-the-logs-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.16-8.9 1. 错误异常的基本描述 # 无法运行预测：内部错误，请检查日志 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [期望单个证书但发现多个 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/expected-a-single-certificate-but-found-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.7-8.9 1. 错误异常的基本描述 # 期望单个证书但发现多个 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [没有可用的主分片用于分片 shard - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/no-primary-shards-available-for-shard-shard-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.2-8.9 1. 错误异常的基本描述 # 没有可用的主分片用于分片 shard 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [脚本正则表达式字符过多 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/scripting-regular-expression-considered-too-many-characters-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.1-7.15 1. 错误异常的基本描述 # 脚本正则表达式字符过多 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [获取索引信息](https://easysearch.cn/knowledge-base/easysearch_api/get-index-info/): 获取指定索引的详细信息，包括别名、映射、设置、默认设置和数据流信息。 API # GET /{index} HEAD /{index} API 的作用 # 该 API 用于获取指定索引的详细信息，返回以下内容： 信息类型 描述 aliases 索引的别名列表及其配置 mappings 索引的字段映射定义 settings 索引的自定义设置 defaults 索引的默认 … - [读取搜索请求时出现未预期的字符串字段 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-read-search-request-unexpected-string-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.x-8.x 1. 错误异常的基本描述 # could not read search request. unexpected string field [field] 表示 Elasticsearch 在解析搜索请求时，在请求体的顶层发现了一个字符串类型的字段，但该字段名并不属于当前 Search API 所支持的合法字段列表。 这是一个请求解析阶段的错误， … - [超时后 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/timed-out-after-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # 超时后 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返回 400、404、409、429、500 … - [跟随者恢复最大并发文件块数配置](https://easysearch.cn/knowledge-base/easysearch_config/replication.follower.index.recovery.max_concurrent_file_chunks/): 配置项作用 # replication.follower.index.recovery.max_concurrent_file_chunks 配置项用于控制跟随者索引恢复时最大并发文件块传输数。 当 Follower 索引从 Leader 集群恢复数据时，多个文件块可以并行传输。此配置决定了可以同时传输多少个块，直接影响恢复速度和资源消耗。 配置项属性 # 配置路径: … - [连接传输异常 (connect_transport_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/connect_transport_exception/): 为什么这个错误发生 # connect_transport_exception 表示尝试连接到远程节点的传输层时失败。这是一个网络连接级别的错误，发生在节点间建立通信连接的过程中。 这个错误可能由以下原因引起： 远程节点不可达：目标节点地址不正确或节点不存在 网络连接问题：网络中断、路由问题或网络配置错误 端口被阻止：防火墙阻止了传输端口（默认 9300） 目标节点未运行： … - [配置文件 UID 不包含任何下划线字符 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/profile-uid-does-not-contain-any-underscore-character-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.2-8.9 1. 错误异常的基本描述 # 配置文件 UID 不包含任何下划线字符 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [页面缓存byte[] 类型页面的权重配置](https://easysearch.cn/knowledge-base/easysearch_config/cache.recycler.page.weight.bytes/): 配置项作用 # cache.recycler.page.weight.bytes 配置项控制 bytes 类型页面在页面缓存中的内存分配权重。 默认值 # 配置类型 # 静态配置 取值范围 # 配置格式 # # 默认配置 cache.recycler.page.weight.bytes: 1.0 # 增加权重 cache.recycler.page.weight.bytes: 2.0 - [a channel closed while connecting - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/a-channel-closed-while-connecting-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # a channel closed while connecting 表示 Elasticsearch 节点在尝试与其他节点建立传输层连接时，连接通道在握手完成之前就被关闭了。这通常发生在节点间通信的初始阶段，意味着目标节点可能在连接建立过程中主动拒绝了连接，或者底层网络在连接建立完成前就断开了。 常见现象 # … - [Easysearch 搜索入门：_search API 与查询流程](https://easysearch.cn/knowledge-base/basic/easysearch-search-basics-api-and-query-flow/): 对于刚开始接触 INFINI Easysearch 的开发者来说，最先打交道的往往是数据的写入，但最核心的价值则体现在搜索上。与传统关系型数据库使用 SQL 不同，Easysearch 使用基于 JSON 的 Query DSL（Domain Specific Language，领域特定语言）来定义查询。 本文将带你入门 Easysearch 的搜索机制，从最基础的 match_all 开始，深入 … - [HTTP 绑定异常 (bind_http_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/bind_http_exception/): 为什么这个错误发生 # bind_http_exception 表示 Easysearch 无法绑定到配置的 HTTP 端口（默认 9200）。这通常发生在节点启动时。 这个错误可能由以下原因引起： 端口被占用：端口已被其他进程占用 权限不足：没有权限绑定到指定端口 地址配置错误：配置的 bind_address 不正确 多个实例：同一机器启动多个实例使用相同端口 防火墙规则：防火墙阻止端口绑 … - [PrefixTree地理形状上的geo-shape查询在特定条件下无法执行——如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/geo-shape-queries-on-prefixtree-geo-shapes-cannot-be-executed-when-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.7-7.15 1. 错误异常的基本描述 # PrefixTree地理形状上的geo-shape查询在特定条件下无法执行— 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 … - [rescore 缺少类型定义 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/missing-rescore-type-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # missing rescore type 是 Elasticsearch 在解析搜索请求 DSL 时抛出的 ParsingException。当 rescore 对象中只声明了公共字段（如 window_size），却没有提供具体的 rescorer 类型（通常是 query）时，解析器无法构造有效的重排器实例，从而触发该异常。 该异常 … - [rescore 阶段执行失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/rescore-phase-failed-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 当查询已经进入 rescore 执行阶段，却在实际重排时发生底层异常，会看到： Rescore Phase Failed 它通常会包装更底层的 IOException 或其他执行期异常。 2. 为什么会发生这个错误 # 和前面几个 rescore 解析错误不同，这个异常说明 DSL 已经通过了解析和基础校验，但在真正执行重排时失败了。 … - [Rollover操作期间别名并发修改异常 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/concurrent-modification-of-alias-during-rollover-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.8-7.1 1. 错误异常的基本描述 # Rollover操作期间别名并发修改异常 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [System Read 线程池队列大小配置](https://easysearch.cn/knowledge-base/easysearch_config/thread_pool.system_read.queue_size/): 配置项作用 # thread_pool.system_read.queue_size 配置项用于控制系统读取线程池的队列大小。 配置项属性 # 配置路径: thread_pool.system_read.queue_size 数据类型: Integer（整数） 默认值: 2000 是否可选: 是 作用域: NodeScope（节点级别） 动态更新: 否（需要重启节点生效） 配置建议 # … - [不支持小数时间间隔，请使用正整数 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/decimal-time-interval-not-supported-please-use-an-positive-integer-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.8-8.11 1. 错误异常的基本描述 # decimal time interval not supported; please use a positive integer 是 Elasticsearch 在解析时间值（TimeValue）时抛出的异常。该错误表明：在期望一个正整数 + 时间单位组合的位置，传入了小数或非法格式的时间值，导致解析器拒绝该请求。 该异常通常在请 … - [任务未运行且尚未存储结果 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/task-isn-t-running-and-hasn-t-stored-its-results-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 任务未运行且尚未存储结果 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [传入集群状态版本 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/incoming-cluster-state-version-how-to-solve-this-elasticsearch-exception/): 适用版本： 7-7.15 1. 错误异常的基本描述 # 传入集群状态版本 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [作业调度器请求超时配置](https://easysearch.cn/knowledge-base/easysearch_config/jobscheduler.request_timeout/): 配置项作用 # jobscheduler.request_timeout 配置项用于控制作业调度器在进行搜索请求时的超时时间。 此配置主要影响 Job Sweeper（作业清理器）执行搜索操作时的超时控制，确保在集群负载高或网络延迟的情况下，搜索请求能够在合理时间内完成或超时。 配置项属性 # 配置路径: jobscheduler.request_timeout 数据类型: … - [分片 %s rollup 任务已取消 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/shard-s-rollup-cancelled-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.7-8.9 1. 错误异常的基本描述 # 分片 %s rollup 任务已取消 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [启动部署超时 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/starting-deployment-timed-out-after-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.5-8.9 1. 错误异常的基本描述 # 启动部署超时 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [命令缺少分片参数 – 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/command-missing-the-shard-parameter-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 命令缺少分片参数 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [总断路器内存限制配置](https://easysearch.cn/knowledge-base/easysearch_config/indices.breaker.total.limit/): 配置项作用 # indices.breaker.total.limit 配置项控制所有断路器的总内存限制上限。 默认值 # 95%（JVM 堆内存的 95%） 配置类型 # 动态配置 配置格式 # # 默认配置 indices.breaker.total.limit: 95% # 调整限制 indices.breaker.total.limit: 90% - [拒绝请求，因为已存在领导者 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/rejecting-request-as-there-is-already-a-leader-how-to-solve-this-elasticsearch-exception/): 适用版本： 7-8.9 1. 错误异常的基本描述 # 拒绝请求，因为已存在领导者 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [收到无效时间戳输入 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/invalid-timestamp-received-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Invalid timestamp received; ... 表示 Elasticsearch 在将输入文本转换为时间戳（datetime 类型）字面量时解析失败，底层会抛出 DateTimeParseException，并在外层封装为当前异常信息。 与纯 date 类型解析不同，此错误通常涉及完整的日期加时间字段，可能还包含毫秒、时 … - [无效的时间分钟值，可能值应在0到59之间——如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/invalid-time-minute-value-possible-values-may-be-between-0-and-59-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # 无效的时间分钟值，可能值应在0到59之间— 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法启动 Datafeed，分配说明显示失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-start-datafeed-allocation-explanation-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # Could not start datafeed; allocation explanation [...] 表示 Elasticsearch 机器学习模块在尝试启动 datafeed 时，持久化任务（Persistent Task）未能成功分配到任何节点，导致启动请求被拒绝。 常见现象 # 调用 POST … - [期望数值但发现了其他类型 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/expected-number-but-found-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 期望数值但发现了其他类型 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [未能删除段文件中未引用的文件 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-remove-files-not-referenced-in-segment-file-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.11-7.13 1. 错误异常的基本描述 # 未能删除段文件中未引用的文件 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [查询缓存全段配置](https://easysearch.cn/knowledge-base/easysearch_config/indices.queries.cache.all_segments/): 配置项作用 # indices.queries.cache.all_segments 配置项控制是否缓存所有段的查询结果。启用后会占用更多内存但提高缓存命中率。 默认值 # false 配置类型 # 动态配置 配置格式 # # 默认配置：只缓存部分段 indices.queries.cache.all_segments: false # … - [查询规则库列表](https://easysearch.cn/knowledge-base/easysearch_api/get-ruleset-list/): 获取系统中所有规则库（规则仓库）的列表和概要信息。 API 格式 # GET .match_rules/_search POST .match_rules/_search API 作用 # 该 API 用于列出所有可用的规则库，支持： 查看所有规则库 按状态、标签等条件过滤 分页浏览规则库 获取规则库的元数据信息 API 参数 # 查询参数 # … - [没有ILM历史模板 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/no-ilm-history-template-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.11-8.9 1. 错误异常的基本描述 # 没有ILM历史模板 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [等待任务完成超时 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/timed-out-waiting-for-completion-of-tasks-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.7-8.8 1. 错误异常的基本描述 # 等待任务完成超时 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [节点不再是 master term - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/node-is-no-longer-master-for-term-how-to-solve-this-elasticsearch-exception/): 适用版本： 7-7.15 1. 错误异常的基本描述 # 节点不再是 master term 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [节点健康检查失败异常 (node_health_check_failure_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/node_health_check_failure_exception/): 为什么这个错误发生 # node_health_check_failure_exception 表示节点的文件系统健康检查失败。当 FsHealthService 报告文件系统不健康时，该节点需要从集群中移除。 这个错误可能由以下原因引起： 磁盘故障：物理磁盘故障或损坏 磁盘空间不足：磁盘使用率超过配置的阈值 磁盘 IO 错误：磁盘读写错误 文件系统损坏：文件系统元数据损坏 只读文件系统：文件 … - [获取升级状态](https://easysearch.cn/knowledge-base/easysearch_api/get-upgrade-status/): 获取一个或多个索引的 Lucene 段升级状态，用于监控由 POST /_upgrade API 发起的索引升级进度。 API 格式 # GET /_upgrade GET /{index}/_upgrade API 作用 # 该 API 用于检查索引中需要升级的 Lucene 段的大小和状态。升级过程会将旧版本的 Lucene 段格式转换为当前版本，以确保兼容性和性能。 API 参数 # … - [解析 modelPlot 失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-modelplot-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 解析 modelPlot 失败 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [解析操作员用户文件错误 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/error-parsing-operator-users-file-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.11-8.9 1. 错误异常的基本描述 # 解析操作员用户文件错误 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [达到推理处理器最大数量限制——如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/max-number-of-inference-processors-reached-total-inference-processors-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.6-7.15 1. 错误异常的基本描述 # 达到推理处理器最大数量限制— 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [配置驱动的密钥提示功能在6.0.0版本中已弃用，请使用密钥存储库——如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/config-driven-secret-prompting-was-deprecated-in-6.0.0-use-the-keystore-how-to-solve-this-elasticsearch-exception/): 适用版本： 7-7.15 1. 错误异常的基本描述 # 配置驱动的密钥提示功能在6.0.0版本中已弃用，请使用密钥存储库— 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [集群恢复时间延迟配置](https://easysearch.cn/knowledge-base/easysearch_config/gateway.recover_after_time/): 配置项作用 # gateway.recover_after_time 配置项控制集群状态恢复前的延迟时间。当必要的节点可用后，系统会等待指定的时间间隔后才开始恢复集群状态。 是否可选 # 是 默认值 # 0ms (无延迟) 配置项类型 # 静态配置 - 需要重启节点才能生效 配置格式 # # 默认配置（无延迟） gateway.recover_after_time: 0ms # … - [2026 年中国搜索型数据库市场观察与分析](https://easysearch.cn/knowledge-base/insight/china-search-database-market-observation-and-analysis-2026/): 2026 年中国搜索型数据库市场观察与分析 —— 面向技术决策者的行业趋势参考 一、核心摘要 # 步入 2026 年，搜索型数据库在中国企业数字化架构中的基石地位日益巩固，其应用场景已从传统的日志分析、业务搜索，深度扩展至实时数据治理、安全智能分析与 AI 增强检索等领域。在数据规模激增、实时性要求苛刻及自主可控政策深化的多重驱动下，该技术正完成从“高效工具”到“关键业务基础设施”的战略转型。 … - [base_path 末尾不能带斜杠 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/there-should-be-not-trailing-slash-in-the-base-path-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.4-7.17 1. 错误异常的基本描述 # there should be not trailing slash in the base path 表示 Elasticsearch 在执行 S3 仓库 cleanup 时，检测到 base_path 以 / 结尾，因此直接拒绝继续处理。 这里的重点不是查询语法，也不是 S3 服务不可达，而是 cleanup 参数格式不符合实现要 … - [cannot restore index [renamedIndex] because an open index with same name already exists in the cluster - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-restore-index-renamedindex-because-an-open-index-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.5 1. 错误异常的基本描述 # 恢复快照不是覆盖写入现有打开索引。源码中恢复前会先检查目标名字对应的索引是否已经存在且已关闭，如果发现同名索引仍是打开状态，就直接抛出异常，防止把恢复数据与在线写入中的索引混在一起。 常见现象 # 恢复请求里没有明显语法问题，但立即失败。 目标索引在集群中已经存在，并且状态为 open。 常见于演练恢复时忘记改名，或试图把快照直接覆 … - [ConstantScoreQueryBuilder NAME - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/constantscorequerybuilder-name-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-6.8 1. 错误异常的基本描述 # ConstantScoreQueryBuilder NAME 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Easysearch 全文检索详解](https://easysearch.cn/knowledge-base/basic/easysearch-full-text-search-guide/): 在现代数据系统中，“全文检索”是信息检索的核心功能之一。无论是在网站搜索框里键入关键词，还是在企业海量日志、文档库中搜索内容，背后都离不开高效的全文检索引擎。 在这篇文章中，我们将用通俗易懂、技术风格的语言解释： 什么是全文检索 全文检索的应用场景 Easysearch 如何实现全文检索能力 这篇文章既适合非专业读者，也能让技术人员对 Easysearch 的实现细节有直观理解。 一、什么是 … - [failed to parse date field with format - 日期字段与指定格式不匹配](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-date-field-with-format-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # failed to parse date field [value] with format [format] 表示 Elasticsearch 已经明确知道要用哪个日期格式解析，但实际值和该格式无法匹配。保留代码显示，底层日期格式化器抛出 IllegalArgumentException 后，外层会包装成当前异常，并带上原始值和格式 … - [QueryStringQueryBuilder NAME 必须提供查询参数 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/querystringquerybuilder-name-must-be-provided-with-a-query-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # QueryStringQueryBuilder NAME 必须提供查询参数 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见 … - [Span within 查询不支持 currentFieldName – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/span-within-query-does-not-support-currentfieldname-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Span within 查询不支持 currentFieldName 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 … - [Transport 主机配置](https://easysearch.cn/knowledge-base/easysearch_config/transport.host/): 配置项作用 # transport.host 配置项用于定义节点的基本网络地址。 配置项属性 # 配置路径: transport.host 数据类型: List<String>（字符串列表） 默认值: 空列表 [] 是否可选: 是 作用域: NodeScope（节点级别） 动态更新: 否（需要重启节点生效） 配置建议 # 所有网络 # transport: host: … - [不再是主分片 (no_longer_primary_shard_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/no_longer_primary_shard_exception/): 为什么这个错误发生 # no_longer_primary_shard_exception 表示当前节点上的分片不再是主分片。这是因为主分片已经转移到其他节点，当前分片已降级为副本或被标记为过期。 这个错误可能由以下原因引起： 主分片转移：主分片已迁移到其他节点 主分片切换：原主分片故障，新的主分片已被选出 主分片降级：当前分片被标记为过期（stale），不再是主分片 Primary Term … - [不可序列化异常包装器 (not_serializable_exception_wrapper) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/not_serializable_exception_wrapper/): 为什么这个错误发生 # not_serializable_exception_wrapper 是一个包装异常，用于将不可序列化的异常序列化以便在网络上传输。当需要将异常信息从远程节点传递到客户端时使用。 这个错误本身不是一个实际问题，而是用于包装那些无法直接序列化的异常。被包装的异常才是实际问题的根源。 这个包装器可能包装以下类型的异常： 自定义异常：用户定义的不可序列化异常 第三方库异常：第 … - [不支持的聚合类型](https://easysearch.cn/knowledge-base/elasticsearch_error/unsupported-aggregation-type-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.11-7.13 1. 错误异常的基本描述 # 不支持的聚合类型 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [创建或更新安全角色](https://easysearch.cn/knowledge-base/easysearch_api/create-or-update-security-role/): 在 Easysearch 安全系统中创建新角色或更新现有角色的权限配置。 API 格式 # PUT /_security/role/{name} API 作用 # 该 API 用于创建或更新安全角色： 创建新角色并定义其权限 完全更新现有角色的配置 定义集群级别和索引级别的权限 API 参数 # 路径参数 # 参数 类型 是否必填 默认值 描述 {name} String … - [发现兼容当前版本的nodeMetadata - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/found-nodemetadata-which-is-compatible-with-current-version-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.2-7.15 1. 错误异常的基本描述 # 发现兼容当前版本的nodeMetadata 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [只能在 keyword、text 和 wildcard 字段上使用通配符查询 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/can-only-use-wildcard-queries-on-keyword-text-and-wildcard-fields-not-on-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.9-8.9 1. 错误异常的基本描述 # Can only use wildcard queries on keyword, text and wildcard fields - not on [...] 是 Elasticsearch 在执行 wildcard 查询时抛出的类型校验异常。该错误表明：你正在对一个不支持通配符查询的字段类型发起 wildcard 查 … - [只能在keyword、text和wildcard字段上使用前缀查询，而不能在其他字段上使用 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/can-only-use-prefix-queries-on-keyword-text-and-wildcard-fields-not-on-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.9-8.9 1. 错误异常的基本描述 # Can only use prefix queries on keyword, text and wildcard fields - not on [...] 是 Elasticsearch 在执行前缀查询（prefix query）时，因目标字段类型不支持而抛出的异常。该异常属于 illegal_argument_exception … - [字段fieldName不是geo_point类型字段 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/field-fieldname-is-not-a-geo-point-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 字段fieldName不是geo_point类型字段 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能 … - [无法找到过滤器 resourceId – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unable-to-find-filter-resourceid-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.2-8.9 1. 错误异常的基本描述 # 无法找到过滤器 resourceId 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法解析 inline template - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-inline-template-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Could not parse inline template 是 Elasticsearch 在使用 Mustache 模板引擎处理 inline 模板时抛出的 ParsingException。当 Elasticsearch 尝试将对象形式的 inline template 复制为 JSON 字符串并转换为脚本文本时， … - [无法识别的丰富策略类型 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unrecognized-enrich-policy-type-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.5-8.9 1. 错误异常的基本描述 # 无法识别的丰富策略类型 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法重构查询以进行签名验证 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-reconstruct-query-for-signature-verification-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # 无法重构查询以进行签名验证 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [映射类型名过长（限制255字符）—— 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/mapping-type-name-type-is-too-long-limit-is-length-255-but-was-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # 映射类型名过长（限制255字符）— 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [未找到期望的节点 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/desired-nodes-not-found-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.1-8.9 1. 错误异常的基本描述 # 未找到期望的节点 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [标准化通配符查询 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/normalized-wildcard-query-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.3-8.9 1. 错误异常的基本描述 # 标准化通配符查询 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [检查期间断开连接 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/disconnected-during-check-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.3-7.15 1. 错误异常的基本描述 # 检查期间断开连接 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [每节点心跳连接数配置](https://easysearch.cn/knowledge-base/easysearch_config/transport.connections_per_node.ping/): 配置项作用 # transport.connections_per_node.ping 配置项控制集群中每个节点之间用于心跳检测（Ping）的并发连接数。心跳连接用于故障检测机制，定期检测节点是否存活。这是数据量最小但最关键的连接类型，直接影响集群的故障检测速度。 配置项类型 # 该配置项为静态配置，需要在启动时设置，修改后需要重启节点才能生效。 默认值 # 1 是否必需 # 可选配置项（ … - [管理组件模板](https://easysearch.cn/knowledge-base/easysearch_api/manage-component-template/): 创建、获取、删除可重用的组件模板（Component Templates）。 API # PUT /_component_template/{name} POST /_component_template/{name} GET /_component_template GET /_component_template/{name} DELETE … - [节点并发异步搜索数量限制](https://easysearch.cn/knowledge-base/easysearch_config/async_search.node_concurrent_running_searches/): 配置项作用 # async_search.node_concurrent_running_searches 配置项限制每个节点（协调节点）同时运行的异步搜索数量。当达到此限制时，新的异步搜索请求将被拒绝，直到有正在运行的搜索完成。 配置项类型 # 该配置项为动态配置，可以在运行时通过集群更新 API 进行修改，无需重启节点。 默认值 # 20 是否必需 # 可选配置项 取值范围 # 0 … - [解析 Watch Input 时数组项应为字符串却读到其他类型 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-input-for-watch-expected-a-string-value-as-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # could not parse [TYPE] input for watch [watchId]. expected a string value as an [field] item but found [token] instead 表示 Watch input 中某个数组字段要求每一项都是字符串，但实际读到了其他 token 类 … - [解析正则表达式文件错误 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/error-parsing-regular-expression-file-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 解析正则表达式文件错误 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [请求的NameID格式与允许的NameID格式不匹配 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/the-requested-nameid-format-doesn-t-match-the-allowed-nameid-format-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.7-7.15 1. 错误异常的基本描述 # 请求的NameID格式与允许的NameID格式不匹配 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返 … - [距离特性查询 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/distance-feature-query-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.3-8.9 1. 错误异常的基本描述 # 距离特性查询 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [跨集群复制跟随者恢复块大小配置](https://easysearch.cn/knowledge-base/easysearch_config/replication.follower.index.recovery.chunk_size/): 配置项作用 # replication.follower.index.recovery.chunk_size 配置项用于控制跟随者恢复期间索引文件传输的块大小。 配置项属性 # 配置路径: replication.follower.index.recovery.chunk_size 数据类型: ByteSizeValue（字节大小） 默认值: 1mb 有效范围: 1MB-1GB 是否可选: … - [集群clusterAlias没有剩余种子节点 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/no-seed-node-left-for-cluster-clusteralias-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.8-8.9 1. 错误异常的基本描述 # 集群clusterAlias没有剩余种子节点 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [页面缓存堆内存限制配置](https://easysearch.cn/knowledge-base/easysearch_config/cache.recycler.page.limit.heap/): 配置项作用 # cache.recycler.page.limit.heap 配置项用于控制页面缓存回收器（Page Cache Recycler）可以使用的最大堆内存量。该回收器负责缓存和重用固定大小的内存页（16KB），包括 byte[]、int[]、long[] 和 Object[] 四种类型，以减少频繁的内存分配和垃圾回收开销。 通过合理设置此配置，可以在内存使用效率和性能之间取得平衡。 … - [cannot restore index [index] because it cannot be upgraded - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-restore-index-index-because-it-cannot-be-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.5 1. 错误异常的基本描述 # 恢复快照时，Elasticsearch 不会直接把历史索引原样挂进当前集群，而是会先尝试把快照中的索引元数据升级到当前集群允许的最小兼容版本。如果升级过程抛异常，就会报 cannot restore index [index] because it cannot be upgraded。 常见现象 # 快照文件能识别，恢复动作也开始 … - [Dis max 查询需要在 queries 字段中至少包含一个子句 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/dis-max-requires-queries-field-with-at-least-one-clause-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Dis max 查询需要在 queries 字段中至少包含一个子句 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [GET 请求线程池配置](https://easysearch.cn/knowledge-base/easysearch_config/thread_pool.get/): 配置项作用 # thread_pool.get 相关配置项控制用于处理 GET 请求的线程池。GET 请求包括单文档查询（如 GET 操作）等获取数据的操作。该线程池采用固定大小线程池类型，线程数默认为处理器核心数。 配置项类型 # 该配置项为静态配置，需要在启动时设置，修改后需要重启节点才能生效。 默认值 # thread_pool.get.size: 分配的处理器数（通常为 CPU 核心 … - [include_in_root 参数不能在嵌套对象映射上更新 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/the-include-in-root-parameter-can-t-be-updated-on-a-nested-object-mapping-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.9-8.9 1. 错误异常的基本描述 # include_in_root 参数不能在嵌套对象映射上更新 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [MapperService INDEX MAPPER DYNAMIC SETTING getKey 为 false – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/mapperservice-index-mapper-dynamic-setting-getkey-is-false-how-to-solve-this-elasticsearch-exception/): 适用版本： 7-7.17 1. 错误异常的基本描述 # MapperService INDEX MAPPER DYNAMIC SETTING getKey 为 false 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日 … - [ModelSnapshot getJobId 删除快照失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/modelsnapshot-getjobid-failed-to-delete-snapshot-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.0-7.6 1. 错误异常的基本描述 # [jobId] 删除快照失败 [snapshotId] 这条异常与上一页类似，但这里失败上下文不是来自 idPair，而是直接来自 ModelSnapshot 对象本身。也就是说，删除流程已经拿到了完整的 model snapshot 实体，并在针对该对象做删除时失败。 它通常出现在更贴近具体文档/对象操作的实现分支上， … - [nested_path 已被 nested 参数取代 —— 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/nested-path-has-been-removed-in-favour-of-the-nested-parameter-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # nested_path 已被 nested 参数取代 — 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接 … - [Painless 正则表达式启用配置](https://easysearch.cn/knowledge-base/easysearch_config/script.painless.regex.enabled/): 配置项作用 # script.painless.regex.enabled 配置项控制是否在 Painless 脚本中启用正则表达式及其复杂度限制。 是否可选 # 是 默认值 # "limited" (启用但限制复杂度) 配置项类型 # 静态配置 - 需要重启节点才能生效 配置格式 # # 默认配置（推荐） script.painless.regex.enabled: … - [Snapshot 线程池最大大小配置](https://easysearch.cn/knowledge-base/easysearch_config/thread_pool.snapshot.max/): 配置项作用 # thread_pool.snapshot.max 配置项用于控制快照线程池的最大线程数。 配置项属性 # 配置路径: thread_pool.snapshot.max 数据类型: Integer（整数） 默认值: (CPU核心数 + 1) / 2，最大不超过 5 是否可选: 是 作用域: NodeScope（节点级别） 动态更新: 是（可以动态更新，无需重启） 配置建议 # … - [SSL KeyManager 初始化失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-initialize-ssl-keymanager-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # SSL KeyManager 初始化失败 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Term intervals query - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/term-intervals-query-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.3-8.9 1. 错误异常的基本描述 # Term intervals query 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Transport TCP Keep-Alive 探测次数配置](https://easysearch.cn/knowledge-base/easysearch_config/transport.tcp.keep_count/): 配置项作用 # transport.tcp.keep_count 配置项用于控制TCP keep-alive 探测在声明连接死亡前的发送次数。 配置项属性 # 配置路径: transport.tcp.keep_count 数据类型: Integer（整数） 默认值: -1（使用操作系统默认值） 是否可选: 是 作用域: NodeScope（节点级别） 动态更新: 否（需要重启节点生效） 配 … - [上下文创建期间发布失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/publishing-failed-during-context-creation-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.9-8.9 1. 错误异常的基本描述 # 上下文创建期间发布失败 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [分片平衡权重配置](https://easysearch.cn/knowledge-base/easysearch_config/cluster.routing.allocation.balance.shard/): 配置项作用 # cluster.routing.allocation.balance.shard 配置项定义分片级别的平衡权重。此配置与 balance.index 配合使用，共同决定集群在分配和重新平衡分片时的权重计算策略。 配置项类型 # 该配置项为动态配置，可以在运行时通过集群设置 API 进行修改。 默认值 # 0.45 是否必需 # 可选配置项（有默认值） 取值范围 # 0.0 … - [删除悬空索引](https://easysearch.cn/knowledge-base/easysearch_api/delete-dangling-index/): 删除指定的悬空索引，将其移动到索引墓地（Index Graveyard）。 API 格式 # DELETE /_dangling/{index_uuid} 注意：API 路径使用 index_uuid 而非 index_name。 API 作用 # 该 API 用于删除集群中的悬空索引。删除操作会将索引移动到索引墓地，标记为已删除。 API 参数 # 路径参数 # 参数 类型 是否必 … - [别名 aliasMapper 名称同时被定义为对象和别名 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/alias-aliasmapper-name-is-defined-both-as-an-object-and-an-alias-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.1-8.9 1. 错误异常的基本描述 # Alias [xxx] is defined both as an object and an alias 是 Elasticsearch 在索引映射（mapping）解析阶段抛出的 MapperParsingException。当 Elasticsearch 发现同一个字段名既被定义为 object 类型， … - [同时设置了 endpoint_suffix 和 secondary endpoint - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/both-an-endpoint-suffix-as-well-as-a-secondary-endpoint-were-set-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.8-8.9 1. 错误异常的基本描述 # Both an endpoint suffix as well as a secondary endpoint were set 表示 Elasticsearch 在构造 Azure 客户端配置时，检测到 endpoint_suffix 与 secondary endpoint 同时存在，因此拒绝继续初始化。 常见现象 # … - [排序参数出现意外的标记](https://easysearch.cn/knowledge-base/elasticsearch_error/unexpected-token-token-for-order-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.16-8.9 1. 错误异常的基本描述 # 排序参数出现意外的标记 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [数据流 dataStreamName 已存在 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/data-stream-datastreamname-already-exists-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.11-8.11 1. 错误异常的基本描述 # 数据流 dataStreamName 已存在 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法序列化ID为config getId的数据馈送配置 – 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-serialise-datafeed-config-with-id-config-getid-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.3 1. 错误异常的基本描述 # 无法序列化ID为config getId的数据馈送配置 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可 … - [无法解析数据路径 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unable-to-resolve-data-path-for-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.2-8.9 1. 错误异常的基本描述 # 无法解析数据路径 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法解析日期时间，期望日期字段为数字或 (expected date field to be either a number or a) - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-date-time-expected-date-field-to-be-either-a-number-or-a-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # could not parse date/time. expected date field to be either a number or a DateMath string 是 Elasticsearch 在解析日期类型字段时抛出的典型异常。该错误表示 Elasticsearch … - [无法解析监视器条件，某个字段期望是对象（Could not parse condition for watch. expected an object for field）- 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-condition-for-watch-expected-an-object-for-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.x 1. 错误异常的基本描述 # could not parse [...] condition for watch [...]. expected an object for field [...] but found [...] instead 是 Elasticsearch Watcher 在解析告警条件（condition）时抛出的异常。该错误表示： … - [未知的月份数字 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unknown-month-number-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 未知的月份数字 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [查询嵌入模型](https://easysearch.cn/knowledge-base/easysearch_api/get-embedding-model/): API 状态说明 # 在 Easysearch 中，不存在 GET /_ai/embeddings/{model} API。 相关的 AI 嵌入功能 # 虽然不存在 GET /_ai/embeddings/{model} API，但 Easysearch 提供了其他嵌入相关功能： 已废弃的嵌入 API # 以下 API 已废弃（返回 410 Gone）： POST /_ai/embed … - [查询没有可搜索节点 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/query-no-nodes-to-search-on-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # query: no nodes to search on 表示搜索阶段已经准备执行，但当前请求上下文里找不到任何可用节点来继续搜索。这类问题常见于 scroll、search context、异步搜索或分布式搜索流程中，当本该承载查询上下文的节点已经离线、上下文为空、路由节点不可用，或者集群状态发生变化时，就可能出现这个错误。 从当前源 … - [混合版本集群加入验证失败 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/mixed-version-cluster-join-validation-on-cluster-state-how-to-solve-this-elasticsearch-exception/): 适用版本： 7-7.11 1. 错误异常的基本描述 # 混合版本集群加入验证失败 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [等待请求超时 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/timeout-waiting-for-request-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # 等待请求超时 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返回 400、404、409、429、500 … - [策略不能为空——如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/policy-must-not-be-empty-how-to-solve-this-elasticsearch-exception/): 适用版本： 7-8.9 1. 错误异常的基本描述 # 策略不能为空— 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [索引已关闭 (index_closed_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/index_closed_exception/): 为什么这个错误发生 # index_closed_exception 表示尝试对一个已关闭的索引执行操作。当索引被关闭后，它不会消耗集群资源（除元数据外），但也不能进行任何读写操作。 这个错误可能由以下原因引起： 索引被手动关闭：用户通过 API 显式关闭了索引 操作已关闭索引：尝试对已关闭的索引执行搜索、索引、更新等操作 自动关闭策略：某些自动化工具或策略可能会关闭不活跃的索引 批量操作包含 … - [聚合初始化异常 (aggregation_initialization_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/aggregation_initialization_exception/): 为什么这个错误发生 # aggregation_initialization_exception 表示聚合初始化阶段失败。 如何修复 # 1. 检查聚合语法 # GET /<index>/_search { "aggs": { "my_agg": { "terms": { "field": … - [自动检测意外终止 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unexpected-death-of-autodetect-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 自动检测意外终止 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [解析 Watch Input 时缺少输入类型字段 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-input-for-watch-expected-field-indicating-the-input-type-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # could not parse input for watch [watchId]. expected field indicating the input type; but found [token] instead 表示 Elasticsearch 在解析 watch 的 input 对象时， … - [超越关键词匹配：Easysearch 如何用向量检索实现语义搜索](https://easysearch.cn/knowledge-base/basic/easysearch-vector-search-semantic-guide/): 引言 # 想象这样一个场景：你在公司内部的知识库里搜索：“接口偶尔超时，但日志没看到错误”，却一无所获。然而，系统中明明存在一篇名为《服务响应延迟排查指南》的文章。这并不是数据缺失，而是传统搜索引擎的局限——它“只认字，不认意”。它不知道“超时”≈“延迟”，“没报错”≈“无明显异常”。为了解决这个问题，现代搜索系统引入了 向量检索 技术，让搜索不再局限于关键词匹配，而是真正开始“理解语义”。本文 … - [配置的URL为空，请配置有效的URL - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/configured-url-is-empty-please-configure-a-valid-url-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 配置的URL为空，请配置有效的URL 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [action 的时间字段解析失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-action-failed-to-parse-field-as-time-value-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # could not parse action [watchId/actionId]. failed to parse field [field] as time value 表示某个 action 的时间字段在解析时失败，例如节流时间字段不符合格式要求。 2. 为什么会发生这个错误 # 保留代码显示， … - [Generation = manifest getGlobalGeneration - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/generation-manifest-getglobalgeneration-how-to-solve-this-elasticsearch-exception/): 适用版本： 7-7.5 1. 错误异常的基本描述 # Generation = manifest getGlobalGeneration 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判 … - [HipChat 账户缺少必需的 room 设置 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/invalid-hipchat-account-name-missing-required-room-setting-setting-for-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # 在使用 Elasticsearch Watcher 的 HipChat 通知功能时，如果配置了 integration 类型的 HipChat 账户，但未在账户设置中指定 room 参数，Elasticsearch 会在加载该账户配置时直接抛出 SettingsException 异常，并拒绝启动或加载该 Watcher 账户。 典型 … - [Invalid description date format - 描述性日期格式无效如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/invalid-description-date-format-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # invalid {description} date format {text} 表示某个由 description 指明语义的日期文本格式无效，Elasticsearch 无法将其解析为合法的日期对象。该异常通常在调用 DateUtils.beginningOfTheDay(...) 或 endOfTheDay(...) 等日期处理方 … - [LinearRing 中的点数无效 – 必须大于等于 4 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/invalid-number-of-points-in-linearring-found-must-be-4-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # LinearRing 中的点数无效 – 必须大于等于 4 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口 … - [Script score 查询无法执行时 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/script-score-queries-cannot-be-executed-when-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.7-7.15 1. 错误异常的基本描述 # Script score 查询无法执行时 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [TCP Keepalive 空闲时间配置](https://easysearch.cn/knowledge-base/easysearch_config/network.tcp.keep_idle/): 配置项作用 # network.tcp.keep_idle 配置项用于控制TCP 连接在空闲多长时间后开始发送 keepalive 探测包。 当连接在指定时间内没有数据传输时，系统会启动 TCP keepalive 机制，开始发送探测包来确认连接是否仍然活跃。 配置项属性 # 配置路径: network.tcp.keep_idle 数据类型: Integer（整数，秒） 默认值: -1（使用 … - [unit not supported for date math - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unit-not-supported-for-date-math-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # unit [u] not supported for date math [expr] 是 Elasticsearch 在解析日期数学表达式（date math）时抛出的异常。当你在索引模式、查询条件或 API 参数中使用日期数学表达式（如 now-1d、now+2h）时，如果其中的时间单位不在 Elasticsearch 支持的范围 … - [Unknown array - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unknown-array-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.13 1. 错误说明 # unknown array 是 Elasticsearch 在解析快照仓库（Snapshot Repository）元数据文件时抛出的 ElasticsearchParseException 异常。当 Elasticsearch 读取快照元数据（如 index-*.st 或 snap-*.dat 文件）时，期望遇到特定名称的数组字段（ … - [Warmer 线程池核心大小配置](https://easysearch.cn/knowledge-base/easysearch_config/thread_pool.warmer.core/): 配置项作用 # thread_pool.warmer.core 配置项用于控制索引预热线程池的核心线程数。 Warmer 线程池用于预取索引数据，预热全局序号等数据结构，提高查询性能。 配置项属性 # 配置路径: thread_pool.warmer.core 数据类型: Integer（整数） 默认值: 1 是否可选: 是 作用域: NodeScope（节点级别） 动态更新: 是（可以动态 … - [任务ID不存在 – 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/the-task-with-id-doesn-t-exist-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 任务ID不存在 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [任务ID和分配ID不存在 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/the-task-with-id-and-allocation-id-doesn-t-exist-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 任务ID和分配ID不存在 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [任务在启动前被取消 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/task-cancelled-before-starting-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.15-8.9 1. 错误异常的基本描述 # 任务在启动前被取消 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [作业打开超时 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/opening-job-timed-out-after-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.11-8.4 1. 错误异常的基本描述 # 作业打开超时 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返回 400、404、409、429、500 … - [写入操作失败 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-write-operation-operation-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 写入操作失败 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [分片似乎未损坏 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/shard-does-not-seem-to-be-corrupted-at-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # 分片似乎未损坏 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [列出分片存储元数据失败 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-list-store-metadata-for-shard-request-shardid-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Failed to list store metadata for shard [request.shardId] 出现在节点本地执行 listStoreMetadata(request) 失败时。这里不是查询链路，也不是仓库列举，而是某个节点在响应“列出该 shard 的本地 store 元数据”请求时抛出了 IOException， … - [创建文档（指定ID）](https://easysearch.cn/knowledge-base/easysearch_api/create-document-with-id/): 使用指定的文档 ID 创建新文档。如果文档已存在，操作将失败。 API # POST /{index}/_create/{id} PUT /{index}/_create/{id} POST /{index}/{type}/{id}/_create PUT /{index}/{type}/{id}/_create API 的作用 # 该 API 用于使用指定的 ID 创建新文档。与 /_doc … - [协调状态拒绝 (coordination_state_rejected_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/coordination_state_rejected_exception/): 为什么这个错误发生 # coordination_state_rejected_exception 表示集群协调层的状态转换被拒绝。这通常发生在主节点选举或集群状态更新期间。 这个错误可能由以下原因引起： 主节点选举：多个节点同时竞选主节点 Term 不匹配：接收到的状态更新 Term 与当前不一致 版本冲突：集群状态版本与预期不符 异步消息：接收到过期的集群状态更新 网络分区：网络分区导致集 … - [单播发现种子主机配置](https://easysearch.cn/knowledge-base/easysearch_config/discovery.zen.ping.unicast.hosts/): 配置项作用 # discovery.zen.ping.unicast.hosts 配置项用于指定集群发现过程中使用的种子主机列表。 新节点通过此配置指定的地址列表发现集群中的现有节点，从而加入集群。 配置项属性 # 配置路径: discovery.zen.ping.unicast.hosts 数据类型: list（字符串列表） 默认值: []（空列表） 是否可选: 是 弃用状态: ⚠️ 已弃 … - [取消关注请求未能被确认 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unfollow-request-failed-to-be-acknowledged-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.12-8.9 1. 错误异常的基本描述 # 取消关注请求未能被确认 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [字段 fieldName 不支持 ShapeType LINEARRING 查询 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/field-fieldname-does-not-support-shapetype-linearring-queries-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.16-8.9 1. 错误异常的基本描述 # 字段 fieldName 不支持 ShapeType LINEARRING 查询 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判 … - [字段年份日值无效，期望字符串或数值或数组——如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/invalid-year-day-value-for-field-expected-string-number-value-or-an-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # 字段年份日值无效，期望字符串或数值或数组— 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [尝试从空坐标节点获取维度数 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/attempting-to-get-number-of-dimensions-on-an-empty-coordinate-node-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.0-8.9 1. 错误异常的基本描述 # attempting to get number of dimensions on an empty coordinate node 是 Elasticsearch 在处理地理空间数据（geo_point、geo_shape）时抛出的异常。该错误表示代码尝试从一个空的坐标节点中读取维度数（2D 或 3D），但当前坐标节点没有任何有效的坐 … - [开发者必备：Easysearch 常见问题解答汇总](https://easysearch.cn/knowledge-base/faq/easysearch-developer-essential-faq-guide/): 对于开发者和运维工程师而言，Easysearch 既是一个强大的搜索与分析引擎，也是一个需要理解细节和最佳实践的平台。本文旨在通过常见问题与解答整理，帮助工程师快速定位问题、加速开发、提升系统稳定性。 一、什么是 Easysearch？ # Easysearch 是一款由 INFINI Labs 推出的分布式搜索引擎，具备全文检索、结构化检索、聚合分析、向量检索等多种能力，可用于日志检索、报表 … - [无法启动数据框转换——如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unable-to-start-data-frame-transform-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.2-7.4 1. 错误异常的基本描述 # 无法启动数据框转换— 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法在 indexPath 找到有效的分片 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unable-to-find-a-valid-shard-at-indexpath-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 无法在 indexPath 找到有效的分片 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法将任务结果转换为 XContent 格式 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/couldn-t-convert-task-result-to-xcontent-for-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # 无法将任务结果转换为 XContent 格式 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法解析 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unable-to-parse-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # 无法解析 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [未知的指定ID数据分析任务——如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/no-known-data-frame-analytics-with-id-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.3-8.9 1. 错误异常的基本描述 # 未知的指定ID数据分析任务— 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [查询所有搜索管道](https://easysearch.cn/knowledge-base/easysearch_api/get-all-search-pipelines/): 此 API 用于获取 Easysearch 集群中所有搜索管道（Search Pipeline）的配置信息。 API # GET /_search/pipeline API 的作用 # 获取集群中所有搜索管道的配置信息。搜索管道用于自定义搜索请求和响应的处理流程。返回的信息包括： 管道 ID：每个管道的唯一标识符 配置内容：管道的处理器配置（请求处理器和响应处理器） 描述信息：管道的标签和描 … - [网络断开时重连配置](https://easysearch.cn/knowledge-base/easysearch_config/discovery.zen.fd.connect_on_network_disconnect/): 配置项作用 # discovery.zen.fd.connect_on_network_disconnect 配置项用于控制当检测到网络连接断开时，是否在判定节点故障前先尝试重新连接。 配置项属性 # 配置路径: discovery.zen.fd.connect_on_network_disconnect 数据类型: boolean 默认值: false 是否可选: 是 弃用状态: ⚠️ 已 … - [节点失败异常 (failed_node_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/failed_node_exception/): 为什么这个错误发生 # failed_node_exception 表示在某个节点上执行操作时失败。这是一个包装异常，用于报告特定节点的操作失败情况，通常出现在广播操作或多节点操作中。 这个错误可能由以下原因引起： 节点故障：目标节点宕机、崩溃或无响应 网络问题：与目标节点的网络连接中断或超时 资源不足：目标节点 CPU、内存或磁盘资源不足 操作执行失败：目标节点在执行请求的操作时出错 超时： … - [随机分数种子必须是整数、长整型或字符串，而不能是其他类型——如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/random-score-seed-must-be-an-int-long-or-string-not-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # 随机分数种子必须是整数、长整型或字符串，而不能是其他类型— 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [集群故障检测跟随者检查超时配置](https://easysearch.cn/knowledge-base/easysearch_config/cluster.fault_detection.follower_check.timeout/): 配置项作用 # cluster.fault_detection.follower_check.timeout 配置项定义了 Leader 节点向每个 Follower 节点发送健康检查请求后的等待超时时间。 当 Leader 需要确认 Follower 节点是否仍然健康和可达时，会发送一个检查请求。如果在此时间内未收到响应，该次检查将被计为失败。 配置项属性 # 配置路径: … - [Canned ACL 配置值无效 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cannedacl-is-not-valid-cannedacl-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # cannedACL is not valid: [cannedACL] 表示 Elasticsearch 在解析 S3 仓库配置中的 canned_acl 时，没有在支持的 ACL 枚举中找到对应值，因此直接拒绝该配置。 从源码片段可以看出，这一步是把字符串与内置枚举逐个比对；只要没有匹配项， … - [Easysearch 能做什么，不能做什么？新手最容易踩的 5 个坑](https://easysearch.cn/knowledge-base/faq/easysearch-what-can-and-cannot-do-5-common-mistakes-for-beginners/): Easysearch 凭借其强大的全文搜索、分布式能力和灵活的分析功能，正成为现代应用不可或缺的一部分。然而，对于刚接触 Easysearch 的开发者来说，由于其架构和设计哲学与传统数据库大相径庭，很容易会将它当成“增强版的数据库”来使用，从而导致各种性能问题、数据不一致，甚至影响整个系统的稳定性。 本文将从 Easysearch 的核心能力出发，明确它适合与不适合的场景，并为你揭示新手最容易踩 … - [Explain VERIFY should be specified at most once - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/explain-verify-should-be-specified-at-most-once-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Explain VERIFY should be specified at most once 表示 EXPLAIN 语句里重复声明了 VERIFY 子句。解析器检测到 ctx.VERIFY().size() > 1 时，会直接报错。 常见现象 # 执行 SQL Explain 时得到 400。 返回里会明确说明 VERIFY … - [FALSE – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/false-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.17 1. 错误异常的基本描述 # FALSE 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [HipChat 账户缺少 profile 设置 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/missing-profile-setting-for-hipchat-account-name-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-6.8 1. 错误说明 # 在 Elasticsearch 6.x 中，HipChat 通知功能是 Watcher 组件的一部分，允许通过 Watcher 向 HipChat 房间发送告警消息。每个 HipChat 账户在配置时必须明确指定 profile 参数，用于决定账户的类型和行为模式。 当 Elasticsearch 在解析 HipChat … - [Watch does not exist - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/watch-does-not-exist-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Watch does not exist 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [watch 的 HTTP input 出现了不允许的数组字段 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-input-for-watch-unexpected-array-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.x 1. 错误异常的基本描述 # could not parse [http] input for watch [id]. unexpected array field [field] 表示 Elasticsearch Watcher 在解析 HTTP input 配置时，遇到了当前字段不支持的数组格式。 在 Watcher 的 HTTP input 定义中，只有少数特 … - [Wrapper Query 未指定 query 字段 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/wrapper-query-has-no-query-specified-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # wrapper query has no [query] specified 是 Elasticsearch 在解析 wrapper 查询时抛出的 ParsingException。该错误表示 Elasticsearch 已经识别到了 wrapper 查询的语法结构，但在读取 query 字段的二进制内容时，发现其值为空（null），因 … - [主节点故障检测间隔配置](https://easysearch.cn/knowledge-base/easysearch_config/cluster.fault_detection.leader_check.interval/): 配置项作用 # cluster.fault_detection.leader_check.interval 配置项控制从节点（Follower）向主节点（Leader）发送健康检查请求的间隔时间。此配置影响集群故障检测的响应速度和网络负载。 配置项类型 # 该配置项为静态配置，需要在启动时设置，修改后需要重启节点才能生效。 默认值 # 1000ms（1秒） 是否必需 # 可选配置项（有默认 … - [保留租约已存在异常 (retention_lease_already_exists_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/retention_lease_already_exists_exception/): 为什么这个错误发生 # retention_lease_already_exists_exception 表示尝试创建一个已经存在的保留租约（retention lease）。保留租约用于确保在软删除（soft delete）模式下，文档的历史版本不会被过早清理。 这个错误可能由以下原因引起： 租约 ID 冲突：使用已存在的租约 ID 创建新租约 重复请求：同一个租约创建请求被重复发送 并发操 … - [内存断路器 Accounting 限制配置](https://easysearch.cn/knowledge-base/easysearch_config/indices.breaker.accounting.limit/): 配置项作用 # indices.breaker.accounting.limit 配置项用于控制Accounting 断路器的内存使用限制。 Accounting 断路器用于跟踪与请求生命周期无关的持久化内存使用，主要是 Lucene 索引段（segments）占用的内存。 配置项属性 # 配置路径: indices.breaker.accounting.limit 数据类型: … - [动态模板语法错误：期望一个命名对象数组 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/dynamic-template-syntax-error-an-array-of-named-objects-is-expected-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.7-8.9 1. 错误异常的基本描述 # dynamic template syntax error: an array of named objects is expected 是 Elasticsearch 在解析动态模板（dynamic_templates）配置时抛出的映射解析异常。该错误表明动态模板的定义结构不符合 Elasticsearch 的语法要求——动态模板必须 … - [命令缺少index参数 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/command-missing-the-index-parameter-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 命令缺少index参数 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [多搜索](https://easysearch.cn/knowledge-base/easysearch_api/multi-search/): 在单个 HTTP 请求中执行多个搜索查询，减少网络往返时间。 API # GET /_msearch POST /_msearch GET /{index}/_msearch POST /{index}/_msearch API 的作用 # Multi Search API 允许在单个请求中执行多个搜索查询，服务器按顺序返回所有结果。 多搜索的优势 # … - [字段数据断路器类型配置](https://easysearch.cn/knowledge-base/easysearch_config/indices.breaker.fielddata.type/): 配置项作用 # indices.breaker.fielddata.type 配置项控制字段数据断路器的实现类型。 默认值 # memory 配置类型 # 动态配置 取值范围 # memory：基于内存的断路器 配置格式 # # 默认配置 indices.breaker.fielddata.type: memory - [字符过滤分析失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-analyze-charfiltering-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 字符过滤分析失败 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无效的参数数据类型 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/invalid-parameter-data-type-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # 无效的参数数据类型 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法为发布到节点而序列化集群状态 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-serialize-cluster-state-for-publishing-to-node-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 无法为发布到节点而序列化集群状态 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法索引所有结果 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-index-all-results-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.6-7.6 1. 错误异常的基本描述 # 无法索引所有结果 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法解析监视器的转换，解析失败，必须是一个 (Could not parse transform for watch failed to parse must be a) - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-transform-for-watch-failed-to-parse-must-be-a-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # 无法解析监视器的转换，解析失败，必须是一个 (Could not parse transform for watch failed to parse must be a) 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果 … - [无法解析监视器触发事件，出现未预期的 Token（Could not parse trigger event for ... unexpected token）- 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-trigger-event-for-for-watch-unexpected-token-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.x 1. 错误异常的基本描述 # could not parse trigger event for [...] for watch [...]. unexpected token [...] 表示 Watcher 在解析触发事件内部内容时，遇到了不应该出现的 JSON token。 与前面的“expected trigger type string field” … - [期望逗号但发现了其他内容 – 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/expected-comma-but-found-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 期望逗号但发现了其他内容 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [查询分片异常 (query_shard_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/query_shard_exception/): 为什么这个错误发生 # query_shard_exception 表示在分片上创建查询时失败。 如何修复 # 1. 检查字段映射 # GET /<index>/_mapping 2. 验证查询语法 # 确保查询字段和值正确。 3. 重试查询 # GET /<index>/_search { "query": { "term": { … - [查询集群健康（Cat格式）](https://easysearch.cn/knowledge-base/easysearch_api/get-cluster-health-cat-format/): 以紧凑的表格形式返回集群健康状态信息。 API 格式 # GET /_cat/health API 作用 # 该 API 以表格形式返回集群健康状态： 显示集群名称和健康状态 显示节点数量（总节点和数据节点） 显示分片统计信息 显示待处理任务信息 显示活跃分片百分比 API 参数 # 查询参数 # 参数 类型 是否必填 默认值 描述 format String 否 文本表 … - [模型分配未路由到节点 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/assignment-for-model-with-id-is-not-routed-to-node-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.9-8.11（含机器学习功能版本） 1. 错误说明 # assignment for model with id [xxx] is not routed to node [xxx] 是 Elasticsearch 机器学习（Machine Learning）模块中出现的异常。当 Elasticsearch 尝试对某个已部署的机器学习模型执行更新或管理操作时，发现该模型的分配记录 … - [点被指定了两次 currentFieldName – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/point-specified-twice-currentfieldname-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.4-8.9 1. 错误异常的基本描述 # 点被指定了两次 currentFieldName 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [相同目标的恢复已注册并等待中 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/recovery-with-same-target-already-registered-waiting-for-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # 相同目标的恢复已注册并等待中 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [索引未完全快照无法恢复 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/index-index-wasn-t-fully-snapshotted-cannot-restore-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.14-8.9 1. 错误异常的基本描述 # index [name] wasn't fully snapshotted - cannot restore 表示 Elasticsearch 在校验待恢复索引时，发现该索引在原始快照中存在失败记录，也就是 snapshotInfo 显示它并没有被完整、成功地快照下来。因此在 request.partial() 为 false 的情况 … - [自动导入悬空索引配置](https://easysearch.cn/knowledge-base/easysearch_config/gateway.auto_import_dangling_indices/): 配置项作用 # gateway.auto_import_dangling_indices 配置项用于控制是否自动检测并导入悬空索引（dangling indices）。 悬空索引是指那些数据已写入磁盘，但不存在于当前集群元数据中的索引。这通常发生在集群出现分区、节点故障等异常情况后。 配置项属性 # 配置路径: gateway.auto_import_dangling_indices 数据类 … - [解析 Watch 时出现未预期字段 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-watch-unexpected-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # could not parse watch [id]. unexpected field [field] 表示 Elasticsearch 在解析一个 watch 定义时，读到了当前版本不认识、也不允许出现在该位置的字段名，因此直接抛出 ElasticsearchParseException。 这类错误通常发生在创建或更新 watch … - [解析作业配置失败 jobId - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-job-configuration-jobid-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 解析作业配置失败 jobId 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [解析字段时出现未知参数 fieldName 错误 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/error-parsing-field-name-with-unknown-parameter-fieldname-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.16-8.7 1. 错误异常的基本描述 # 解析字段时出现未知参数 fieldName 错误 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返 … - [训练模型未部署——如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/trained-model-is-not-deployed-how-to-solve-this-elasticsearch-exception/): 适用版本： 8-8.5 1. 错误异常的基本描述 # 训练模型未部署— 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [请求缺少次要身份验证 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/request-is-missing-secondary-authentication-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.7-8.9 1. 错误异常的基本描述 # 请求缺少次要身份验证 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [跨集群复制领导者队列大小配置](https://easysearch.cn/knowledge-base/easysearch_config/replication_leader.queue_size/): 配置项作用 # replication_leader.queue_size 配置项用于控制复制领导者线程池的队列大小。 配置项属性 # 配置路径: replication_leader.queue_size 数据类型: Integer（整数） 默认值: 0（自动计算为 available_processors × 3/2 + 1） 是否可选: 是 作用域: NodeScope（节点级别） 动 … - [analyzer name contains filters - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/analyzer-name-contains-filters-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.2-7.15 1. 错误异常的基本描述 # analyzer [xxx] contains filters [yyy] that are not allowed to run in [mode] mode 是 Elasticsearch 在索引映射（mapping）或索引模板中配置自定义分析器时抛出的异常。该错误的核心含义是： … - [failed to load cached steps for - 加载缓存步骤失败](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-load-cached-steps-for-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.10-8.9 1. 错误异常的基本描述 # failed to load cached steps for 出现在 ILM（Index Lifecycle Management，索引生命周期管理）策略处理链路。源码先调用 parseStepsFromPhase(policyName, phase, phaseJson) 解析缓存的 phase 定义， … - [failed to parse hipchat message, failed to parse field - 解析 HipChat 消息失败：字段解析异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-hipchat-message-failed-to-parse-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-6.8（HipChat 功能在更高版本中已废弃或移除） 1. 错误异常的基本描述 # failed to parse hipchat message, failed to parse [field] field 表示 Elasticsearch Watcher 在解析 HipChat 消息时，某个字段（如 room、user）存在，但该字段内部的模板或数组元素解析失败。根据 … - [Fetch Shard Store 线程池核心大小配置](https://easysearch.cn/knowledge-base/easysearch_config/thread_pool.fetch_shard_store.core/): 配置项作用 # thread_pool.fetch_shard_store.core 配置项用于控制分片存储元数据获取线程池的核心线程数。 此线程池负责在分片迁移、恢复等操作中，异步获取各个节点的分片存储元数据信息。 配置项属性 # 配置路径: thread_pool.fetch_shard_store.core 数据类型: Integer（整数） 默认值: 1 是否可选: 是 作用域: … - [HTTP Cookie 重置配置](https://easysearch.cn/knowledge-base/easysearch_config/http.reset_cookies/): 配置项作用 # http.reset_cookies 配置项控制是否重置 HTTP 请求中的 Cookie。由于 Netty 3.5.1 修复了 Cookie 解析问题，此配置默认关闭。 默认值 # false 配置类型 # 静态配置 取值范围 # 布尔值（true/false） 配置格式 # # 默认配置：不重置 http.reset_cookies: false # … - [HTTP 最大分块大小配置](https://easysearch.cn/knowledge-base/easysearch_config/http.max_chunk_size/): 配置项作用 # http.max_chunk_size 配置项设置 HTTP 分块传输编码中单个块的最大大小。这用于将响应分解为更小的块进行网络传输。 默认值 # 8KB 配置类型 # 静态配置 取值范围 # 支持字节单位（如 8KB, 1MB, 10MB） 配置格式 # # 默认配置 http.max_chunk_size: 8kb # … - [Node request getNodeId is not currently shutting down – 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/node-request-getnodeid-is-not-currently-shutting-down-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.14-8.9 1. 错误异常的基本描述 # Node request getNodeId is not currently shutting down 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下 … - [Slack 账户配置缺少必需的 URL 设置 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/invalid-slack-name-account-settings-missing-required-url-setting-setting-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # Watcher 的 Slack action 依赖账户级 webhook URL 配置。Elasticsearch 在加载 Slack 账户时，如果既没有从安全设置里读取到 URL，也没有在普通设置里拿到 URL，就会直接抛出当前异常。 典型报错： invalid slack [alerts] account settings. … - [Watch is running currently cannot ack until finished - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/watch-is-running-currently-cannot-ack-until-finished-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # Watch is running currently cannot ack until finished 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文 … - [从流输入创建多字段统计结果时出错 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/error-trying-to-create-multifield-stats-results-from-stream-input-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 从流输入创建多字段统计结果时出错 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [化繁为简：从安装到运维，体验 Easysearch 的“轻量”哲学](https://easysearch.cn/knowledge-base/install/installation-and-operations-lightweight-philosophy/): 我们体验了 Easysearch 在开发侧的便捷——原生支持中文分词、SQL 查询信手拈来。但在企业级应用中，“开发爽”只是第一步，“运维稳”才是长久之计。 提到 Elasticsearch 的运维，很多人的第一反应是： “除了 ES 还要单独部署一个 Kibana，资源吃紧。” “集群黄了（Yellow）不知道为什么，只能对着黑底白字的终端敲 _cat 命令。” “CPU 飙高不知道是哪个线程 … - [向量索引选项出现未知类型 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unknown-vector-index-options-type-type-for-field-fieldname-how-to-solve-this-elasticsearch-exception/): 适用版本： 8-8.9 1. 错误异常的基本描述 # 向量索引选项出现未知类型 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [在非主节点上刷新异常检测器内存需求请求 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/request-to-refresh-anomaly-detector-memory-requirements-on-non-master-node-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.12-8.4 1. 错误异常的基本描述 # 在非主节点上刷新异常检测器内存需求请求 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [必须大于或等于0 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/must-be-a-greater-than-or-equal-to-0-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.6-8.9 1. 错误异常的基本描述 # 必须大于或等于0 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [意外的 token 类型 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unexpected-token-type-token-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.16-8.9 1. 错误异常的基本描述 # 意外的 token 类型 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [搜索文档](https://easysearch.cn/knowledge-base/easysearch_api/search-document/): 在索引中执行全文搜索、结构化查询、聚合等操作。 API # GET /_search POST /_search GET /{index}/_search POST /{index}/_search GET /_all/_search POST /_all/_search API 的作用 # 该 API 是 Easysearch 的核心搜索接口，支持： 全文搜索 结构化查询 复杂布尔查询 聚 … - [无效的动态名称表达式缺少日期格式 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/invalid-dynamic-name-expression-missing-date-format-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # 无效的动态名称表达式缺少日期格式 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无效的年月值，期望字符串或数字值但找到了其他类型 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/invalid-year-month-value-expected-a-string-or-a-number-value-but-found-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 无效的年月值，期望字符串或数字值但找到了其他类型 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法使用保留字段名mapper.name - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-use-reserved-field-name-mapper-name-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.11-8.9 1. 错误异常的基本描述 # 无法使用保留字段名mapper.name 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法序列化 ID 为 updatedJob.getId() 的任务 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-serialise-job-with-id-updatedjob-getid-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 无法序列化 ID 为 updatedJob.getId() 的任务 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法解析为地址 - 地址必须是 RFC822 编码的字符串或指定对象 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-as-address-address-must-either-be-a-string-rfc822-encoded-or-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # 无法解析为地址 - 地址必须是 RFC822 编码的字符串或指定对象 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 … - [无法重新建立恢复恢复ID – 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-reestablish-recovery-recovery-id-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.9-7.15 1. 错误异常的基本描述 # 无法重新建立恢复恢复ID 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [更新转换状态时出错 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/error-while-updating-state-for-transform-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.5-7.5 1. 错误异常的基本描述 # 更新转换状态时出错 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [未找到已认证用户 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/did-not-find-an-authenticated-user-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 未找到已认证用户 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [查询任务列表](https://easysearch.cn/knowledge-base/easysearch_api/get-task-list/): 获取集群中当前正在运行的任务信息。 API 格式 # GET /_tasks GET /_tasks/{task_id} API 作用 # 该 API 用于检索集群中当前正在运行的任务信息： 查看所有节点的运行任务 按节点、父任务或平铺方式分组显示 过滤特定节点、动作或父任务 等待任务完成后再返回结果 检查任务是否可取消 API 参数 # 路径参数 # 参数 类型 是否必填 默认 … - [没有剩余种子节点异常 (no_seed_node_left_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/no_seed_node_left_exception/): 为什么这个错误发生 # no_seed_node_left_exception 表示无法连接到远程集群的任何种子节点（seed node）。种子节点是用于发现和连接远程集群的初始节点列表。 这个错误可能由以下原因引起： 远程集群不可用：远程集群已关闭或不存在 网络问题：与远程集群的网络连接中断 配置错误：种子节点地址配置错误 端口被阻止：防火墙阻止了传输端口（默认 9300） 远程集群重启：远 … - [父任务被取消 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/parent-task-was-cancelled-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.15-8.9 1. 错误异常的基本描述 # 父任务被取消 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [节点不应连接 (node_should_not_connect_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/node_should_not_connect_exception/): 为什么这个错误发生 # node_should_not_connect_exception 表示节点之间的连接被配置规则阻止。 如何修复 # 1. 检查节点配置 # 验证节点发现和连接配置。 2. 检查集群设置 # GET /_cluster/settings 3. 移除连接排除规则 # PUT /_cluster/settings { "persistent": { … - [范围编码失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-encode-ranges-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 范围编码失败 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [要跟随的索引 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/index-to-follow-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # 要跟随的索引 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [解析 Watch Transform 时应为单个 transform 对象却读到其他 token - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-transform-for-watch-expected-a-transform-object-but-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # could not parse [TYPE] transform for watch [watchId]. expected a transform object; but found [token] instead 表示 Elasticsearch 在解析 transform 数组项时，本应读到一个对象， … - [解析地理点时出错 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/error-parsing-geopoint-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 解析地理点时出错 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [跨集群复制领导者线程池大小配置](https://easysearch.cn/knowledge-base/easysearch_config/replication.leader.thread_pool.size/): 配置项作用 # replication.leader.thread_pool.size 配置项用于控制领导者复制线程池的线程数量。 配置项属性 # 配置路径: replication.leader.thread_pool.size 数据类型: Integer（整数） 默认值: 0（自动计算为 (available_processors × 3/2) + 1） 是否可选: 是 作用域: … - [运行错误 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/error-running-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 运行错误 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返回 400、404、409、429、500 … - [重试次数耗尽后使文档 ID 失效错误 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/error-invalidating-with-doc-id-after-retries-exhausted-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.2-7.15 1. 错误异常的基本描述 # 重试次数耗尽后使文档 ID 失效错误 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [集群状态发布超时配置](https://easysearch.cn/knowledge-base/easysearch_config/cluster.publish.timeout/): 配置项作用 # cluster.publish.timeout 配置项指定主节点向集群发布状态更新操作的超时时间。当主节点将集群状态更新发送到其他节点时，如果在此时间内未收到足够的确认响应，操作将被视为超时。 配置项类型 # 该配置项为静态配置，需要在启动时设置，修改后需要重启节点才能生效。 默认值 # 30000ms（30秒） 是否必需 # 可选配置项（有默认值） 取值范围 # 1ms … - [30分钟上手：Docker 部署 Easysearch 完整教程](https://easysearch.cn/knowledge-base/install/easysearch-docker-deployment-30min-tutorial/): 前言 # 在国产化替代与数据安全备受重视的今天，Easysearch 作为一款由极限科技团队研发的分布式搜索引擎，凭借其对 Elasticsearch API 的高度兼容性、原生集成向量检索以及卓越的硬件利用率，成为了许多企业私有化部署的首选。 对于研发和运维人员来说，如何快速搭建一套稳定运行的测试或生产环境是第一步。本文将基于官方最佳实践，教你如何在 30 分钟内利用 Docker … - [ConfigKey 必须使用一致的方案（http 或 https）—— 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/configkey-must-use-a-consistent-scheme-http-or-https-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.4 1. 错误异常的基本描述 # ConfigKey 必须使用一致的方案（http 或 https）— 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 … - [could not parse message attachment field missing required field - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-message-attachment-field-missing-required-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # could not parse message attachment field. missing required [...] field 是 Elasticsearch Watcher 在解析消息附件（message attachment）字段时抛出的异常。当附件字段定义中缺少必需字段（如 title 或 value）时，就会触发此 … - [hnsw 类型的索引选项需要配置字段 m – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/index-options-of-type-hnsw-requires-field-m-to-be-configured-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # hnsw 类型的索引选项需要配置字段 m 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [HTTP 主机地址绑定配置](https://easysearch.cn/knowledge-base/easysearch_config/http.host/): 配置项作用 # http.host 配置项指定 HTTP 服务绑定的网络主机地址，决定 Easysearch 在哪些网络接口上监听 HTTP 连接。 是否可选 # 是 默认值 # [] (空列表，会使用 network.host 的值) 配置项类型 # 静态配置 - 需要重启节点才能生效 配置格式 # # 绑定到所有接口 http.host: - 0.0.0.0 # 绑定到特定 IP 地 … - [Incoming last accepted term - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/incoming-last-accepted-term-how-to-solve-this-elasticsearch-exception/): 适用版本： 7-7.15 1. 错误异常的基本描述 # Incoming last accepted term 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能 … - [ISM 历史记录启用配置](https://easysearch.cn/knowledge-base/easysearch_config/index_state_management.history.enabled/): 配置项作用 # index_state_management.history.enabled 配置项用于控制是否启用索引状态管理（ISM）的历史记录功能。 启用后，ISM 会记录索引状态变更的历史信息，包括策略执行情况、状态变更、操作日志等，存储在专门的历史索引中。 配置项属性 # 配置路径: index_state_management.history.enabled 数据类型: … - [Jira 账户配置使用了不安全协议 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/invalid-jira-name-account-settings-unsecure-scheme-protocol-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # 这个错误说明 Jira account 的 URL 协议不符合当前安全策略。最常见情况是账户 URL 使用了 http，但当前配置没有显式允许 HTTP，于是 Elasticsearch 直接拒绝该账户。 典型报错： invalid jira [ops_jira] account settings. unsecure scheme … - [JVM GC 监控刷新间隔配置](https://easysearch.cn/knowledge-base/easysearch_config/monitor.jvm.gc.refresh_interval/): 配置项作用 # monitor.jvm.gc.refresh_interval 配置项用于控制JVM GC 监控服务的检查刷新间隔时间。 此配置决定了 JVM GC 监控服务多久检查一次 GC 活动，收集和监控 GC 的统计信息，检查 GC 是否超过预设的阈值。 配置项属性 # 配置路径: monitor.jvm.gc.refresh_interval 数据类型: TimeValue（时间 … - [Location - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/location-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.13 1. 错误异常的基本描述 # Location 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [RareTerms 聚合不支持浮点类型字段 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/rareterms-aggregation-does-not-support-floating-point-fields-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.3-7.7 1. 错误异常的基本描述 # RareTerms 聚合不支持浮点类型字段 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Span first 必须包含 match span query 子句 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/span-first-must-have-match-span-query-clause-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Span first 必须包含 match span query 子句 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 … - [主机列表已设置但类型为 type – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/host-list-for-key-is-set-but-type-is-type-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.5-7.5 1. 错误异常的基本描述 # 主机列表已设置但类型为 type 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [任务在启动前被取消 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/task-cancelled-before-it-started-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.8-7.14 1. 错误异常的基本描述 # 任务在启动前被取消 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [分片恢复异常 (index_shard_recovery_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/index_shard_recovery_exception/): 为什么这个错误发生 # index_shard_recovery_exception 表示分片恢复过程中发生错误。分片恢复是将数据从副本或快照恢复到分片的过程。 这个错误可能由以下原因引起： 源分片不可用：恢复源的分片不可用或数据损坏 网络问题：节点间网络连接失败或超时 磁盘空间不足：目标节点磁盘空间不足 事务日志损坏：事务日志文件损坏导致无法恢复 文件锁定：分片文件被锁定无法访问 版本不兼 … - [加入集群重试次数配置](https://easysearch.cn/knowledge-base/easysearch_config/discovery.zen.join_retry_attempts/): 配置项作用 # discovery.zen.join_retry_attempts 配置项用于控制节点尝试加入集群时，遇到可重试错误后的最大重试次数。 当节点向主节点发送加入请求时，如果遇到 NotMasterException 等可重试错误，系统会根据此配置决定重试多少次。 配置项属性 # 配置路径: discovery.zen.join_retry_attempts 数据类型: … - [升级索引](https://easysearch.cn/knowledge-base/easysearch_api/upgrade-index/): 升级 Easysearch 索引中的 Lucene 段到当前版本。在升级 Easysearch 版本后，旧索引可能包含旧版本的 Lucene 段，需要升级以确保兼容性和性能。 API 格式 # POST /_upgrade POST /{index}/_upgrade API 作用 # 该 API 用于将索引中的 Lucene 段升级到当前版本。升级过程会重写 Lucene 段，使其与当前版本 … - [已取消（Cancelled）- 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cancelled-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 已取消（Cancelled） 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [恢复后清理失败 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-clean-after-recovery-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 恢复后清理失败 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [恢复失败 (recovery_failed_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/recovery_failed_exception/): 为什么这个错误发生 # recovery_failed_exception 表示分片恢复过程失败。恢复是指将数据从一个节点复制到另一个节点的过程，发生在副本创建、节点重启、分片迁移等场景。 这个错误可能由以下原因引起： 网络问题：节点间网络连接中断或不稳定 磁盘空间不足：目标节点磁盘空间不足 数据损坏：源分片数据损坏 超时：恢复过程超过时间限制 并发恢复过多：同时进行的恢复操作过多 传输失败： … - [无效的动态名称表达式 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/invalid-dynamic-name-expression-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # 无效的动态名称表达式 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无效的管道聚合名称 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/invalid-pipeline-aggregation-named-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # 无效的管道聚合名称 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法管理集群告警，因为告警功能已禁用 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-manage-cluster-alerts-because-alerting-is-disabled-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.11-8.9 1. 错误异常的基本描述 # 无法管理集群告警，因为告警功能已禁用 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [映射格式错误：未找到类型名称 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/malformed-mapping-no-type-name-found-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # malformed mapping; no type name found 表示 Elasticsearch 在解析 mapping 定义时，发现传入的 mapping 内容为空，或者缺少它期望的根级类型名称，因此无法确定要创建哪种 mapping 结构。 从当前页面保留的源码看，异常出现在 mapping 反序列化早期阶段。它的重点不 … - [未知属性路径 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unknown-property-path-for-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.9-7.13 1. 错误异常的基本描述 # 未知属性路径 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [查询指定搜索管道](https://easysearch.cn/knowledge-base/easysearch_api/get-specific-search-pipeline/): 此 API 用于获取 Easysearch 集群中一个或多个指定搜索管道（Search Pipeline）的配置信息。 API # GET /_search/pipeline/{id} API 的作用 # 获取指定搜索管道的配置信息。可以查询单个管道或通过逗号分隔查询多个管道。返回的信息包括： 管道 ID：管道的唯一标识符 配置内容：管道的处理器配置（请求处理器和响应处理器） 版本信息：管道 … - [生成源失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-generate-source-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 生成源失败 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [索引不存在与自动创建索引设置 getKey – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/no-such-index-and-auto-create-index-setting-getkey-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-6.8 1. 错误异常的基本描述 # 索引不存在与自动创建索引设置 getKey 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [索引存储类型配置](https://easysearch.cn/knowledge-base/easysearch_config/config_index.store.type/): 配置项作用 # index.store.type 配置项控制索引数据在磁盘上的存储类型。不同的存储类型提供不同的性能特性和功能支持，如内存映射（mmap）可提高某些场景下的性能。 配置项类型 # 该配置项为静态配置，需要在创建索引时设置，创建后不可修改。 默认值 # 根据系统自动选择： - 64位 JVM 且支持 mmap → hybridfs - 其他情况 → fs 是否必需 # 可选配 … - [编译脚本失败 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-compile-type-script-id-using-lang-lang-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 编译脚本失败 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [认证上下文必须包含请求ID - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/authenticated-context-must-include-request-id-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.17-8.9 1. 错误说明 # authenticated context must include request id 是 Elasticsearch 安全模块在认证成功后校验请求上下文时抛出的异常。该异常表示：当前线程的认证上下文（ThreadContext）中未包含 request_id 字段，而该字段是后续审计日志（Audit Log）和请求追踪所必需的。 该异常并 … - [读取搜索请求时出现未知枚举值 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-read-search-request-unknown-value-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.x-8.x 1. 问题含义 # could not read search request. unknown value [value] for [field] field 表示 Elasticsearch 已经识别出了字段名，但该字段的取值不在允许枚举中。 附带源码显示，解析器会对某些字段逐个比对合法值；一旦不匹配，就抛出当前异常。 … - [配置的节点均不可用 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/none-of-the-configured-nodes-were-available-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.17 1. 错误异常的基本描述 # 配置的节点均不可用 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [集群状态上的加入验证 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/join-validation-on-cluster-state-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # 集群状态上的加入验证 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [aborted - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/aborted-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.7+ 1. 错误异常的基本描述 # aborted 是 Elasticsearch 在操作执行过程中抛出的中止错误。当快照、恢复、分片分配或集群管理操作在执行过程中被强制中止时，就会触发此错误。这可能是用户手动取消、超时、资源不足或底层存储问题导致的。 常见现象 # Elasticsearch 返回 HTTP 500 Internal Server Error … - [expected a field indicating the compared path or a comparison operator - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-condition-for-watch-expected-a-field-indicating-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # expected a field indicating the compared path or a comparison operator; but found [token] instead 是 Elasticsearch Watcher 功能中的配置错误。当你在定义 Watcher 的 compare condition（比较条 … - [HTTP 异常 (http_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/http_exception/): 为什么这个错误发生 # http_exception 表示在处理 HTTP 请求时发生错误。这个异常通常在客户端与 Easysearch 服务器通过 HTTP 协议通信时出现。 这个错误可能由以下原因引起： 无效的 HTTP 方法：使用了不支持的 HTTP 方法 请求 URL 错误：请求的 URL 路径不存在或格式错误 请求体格式错误：请求体的 JSON 格式不正确 内容类型错 … - [HTTPS URI中缺少主机名uriString - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/host-is-missing-in-https-uri-uristring-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.2-8.9 1. 错误异常的基本描述 # HTTPS URI中缺少主机名uriString 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [inner hits 数组中的无效令牌 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/invalid-token-in-inner-hits-array-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # inner hits 数组中的无效令牌 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Suggest 阶段发生 I/O 异常 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/i-o-exception-during-suggest-phase-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Suggest 阶段发生 I/O 异常 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Transform 内部搜索重试次数配置](https://easysearch.cn/knowledge-base/easysearch_config/transform.internal.search.backoff_count/): 配置项作用 # transform.internal.search.backoff_count 配置项用于控制Transform 任务在搜索操作失败时的重试次数。 配置项属性 # 配置路径: transform.internal.search.backoff_count 数据类型: Integer（整数） 默认值: 5 是否可选: 是 作用域: NodeScope（节点级别） 动态更新: … - [Transport 不能为空 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/transport-cannot-be-null-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.13-7.15 1. 错误异常的基本描述 # Transport 不能为空 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Unknown field - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unknown-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # unknown field [fieldName] 表示 Elasticsearch 在解析查询时，发现请求中引用的字段在当前索引的 mapping 中不存在。 从源码可见，这个异常在 MultiValueMode 等查询解析路径中抛出，当 context.getFieldType(fieldName) 返回 null 时触发。 典型报 … - [Unknown object - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unknown-object-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.13 1. 错误异常的基本描述 # unknown object 表示 Elasticsearch 在解析快照仓库的元数据文件（如 BlobStoreIndexShardSnapshot）时，遇到了无法识别的对象类型。 从源码可见，这个异常在快照元数据解析路径中抛出，当对象字段名不是预期的 snapshots 或 files 时触发。 典型报错 # … - [ValuesSource type - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/valuessource-type-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.8-7.15 1. 错误异常的基本描述 # ValuesSource type 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Wildcard queries cannot be executed when - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/wildcard-queries-cannot-be-executed-when-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.7-7.15 1. 错误异常的基本描述 # Wildcard queries cannot be executed when 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判 … - [事务日志修剪失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-trim-translog-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 事务日志修剪失败 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [仅支持POINT类型的WKT图元 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/supports-only-point-among-wkt-primitives-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.8-7.15 1. 错误异常的基本描述 # 仅支持POINT类型的WKT图元 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [分片级写入字节数限制配置](https://easysearch.cn/knowledge-base/easysearch_config/cluster.throttle.shard.write.max_bytes/): 配置项作用 # 设置分片级别每秒允许的最大写入字节数。 默认值 # 0b（不限制） 配置格式 # # 每秒最多 50MB cluster.throttle.shard.write.max_bytes: 50mb # 不限制字节数（默认） cluster.throttle.shard.write.max_bytes: 0b - [删除数据流](https://easysearch.cn/knowledge-base/easysearch_api/delete-data-stream/): 此 API 用于删除 Easysearch 集群中的数据流（Data Stream）。删除数据流时，会同时删除该数据流关联的所有后备索引（backing indices）。 API # DELETE /_data_stream/{name} API 的作用 # 删除指定的数据流及其所有后备索引。这是一个不可逆的操作，执行后数据将被永久删除。 删除操作的影响： 删除数据流本身的定义 删除数据流 … - [副本复制初始退避上限配置](https://easysearch.cn/knowledge-base/easysearch_config/indices.replication.initial_retry_backoff_bound/): 配置项作用 # indices.replication.initial_retry_backoff_bound 配置项控制副本复制操作失败后第一次重试的退避时间上限。后续重试的退避时间呈指数增长，每次翻倍，直到达到 indices.replication.retry_timeout 设置的总超时时间。 配置项类型 # 该配置项为动态配置，可以在运行时通过索引设置 API 进行修改。 默认值 # … - [十分钟上手：用 Docker 快速拉起 Easysearch](https://easysearch.cn/knowledge-base/install/getting-started-docker-quick-start/): 对于开发者来说，使用 Docker 是体验 INFINI Easysearch 最快捷的方式。但如果只是简单地启动容器，重启后会导致SSL 证书重置和数据丢失。 为了避免这些坑，本文将教你用“正确的姿势”在 10 分钟内搭建一个配置持久化、证书固定、数据安全的单节点 Easysearch 环境。 核心知识点预告 # 在开始之前，请记住 Easysearch Docker 镜像的两个特殊设定，这能 … - [字段 fieldName 不支持 GeoShapeType.MULTIPOINT 查询 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/field-fieldname-does-not-support-geoshapetype-multipoint-queries-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-6.8 1. 错误异常的基本描述 # 字段 fieldName 不支持 GeoShapeType.MULTIPOINT 查询 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起 … - [尝试解析对象但类型不匹配 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/trying-to-parse-an-object-but-has-a-different-type-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.14 1. 错误异常的基本描述 # 尝试解析对象但类型不匹配 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [必须指定至少一个字段进行排序 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/must-specify-at-least-one-field-for-order-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.16-8.9 1. 错误异常的基本描述 # 必须指定至少一个字段进行排序 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [按主节点数量恢复配置](https://easysearch.cn/knowledge-base/easysearch_config/gateway.recover_after_master_nodes/): 配置项作用 # gateway.recover_after_master_nodes 配置项用于指定集群恢复状态所需要的最少主节点数量。 当集群启动时，只有在达到指定数量的主节点（有资格成为 master 的节点）后，才会开始恢复集群状态。 配置项属性 # 配置路径: gateway.recover_after_master_nodes 数据类型: integer 默认值: 0 最小值: 0 … - [无法序列化 ID 为 datafeedId 的数据馈送配置 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-serialise-datafeed-config-with-id-datafeedid-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.4-8.9 1. 错误异常的基本描述 # 无法序列化 ID 为 datafeedId 的数据馈送配置 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接 … - [无法读取当前时间戳 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-read-the-current-timestamp-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # could not read the current timestamp 表示 Elasticsearch 在需要获取“当前时间”时失败了，常见于 date math 或依赖系统时钟的解析路径。 2. 为什么会发生这个错误 # 虽然很多场景会把它误解为普通查询失败，但它更接近底层时间源或当前时刻解析失败。通常与 now、系统时钟、内 … - [查询所有点-in-time](https://easysearch.cn/knowledge-base/easysearch_api/get-all-point-in-time/): 此 API 用于获取 Easysearch 集群中所有活跃的 Point In Time (PIT) 上下文信息。 API # GET /_pit/_all API 的作用 # 获取集群中所有活跃的 PIT 上下文信息。该 API 会遍历集群中的所有节点，收集并返回所有当前的 PIT ID 及其相关信息，包括： PIT ID：Base64 编码的 PIT 标识符 创建时间：PIT 创建的时间 … - [没有ID为eventId的事件 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/no-event-with-id-eventid-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 没有ID为eventId的事件 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [没有可用节点 (no_node_available_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/no_node_available_exception/): 为什么这个错误发生 # no_node_available_exception 表示客户端无法连接到任何集群节点来执行操作。这通常是客户端连接问题。 这个错误可能由以下原因引起： 集群宕机：所有节点都宕机或不可用 网络隔离：客户端与集群网络隔离 地址配置错误：客户端配置的节点地址不正确 端口错误：连接的端口号不正确 防火墙阻断：防火墙阻止客户端连接 SSL/TLS 配置错误：安全连接配置问题 … - [磁盘高水位线配置](https://easysearch.cn/knowledge-base/easysearch_config/cluster.routing.allocation.disk.watermark.high/): 配置项作用 # cluster.routing.allocation.disk.watermark.high 配置项用于设置磁盘使用率的高水位线。 当一个节点的磁盘使用率超过此阈值时： 不允许在该节点上分配新的分片 现有的分片会被迁移到其他节点 这是防止磁盘空间被完全占用的关键保护机制。 配置项属性 # 配置路径: … - [解析 Email 模板时存在未知字段 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-email-template-unknown-field-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # could not parse email template. unknown field [{}.{}] field 是 Elasticsearch Watcher 在解析邮件动作（Email Action）的模板配置时抛出的解析异常。该错误表明：在 email 模板对象内部，出现了一个当前版本 Elasticsearch 无法识别 … - [解析仓库失败 - 未知字段 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-repository-unknown-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # failed to parse repository [{}]; unknown field [{}] 表示 Elasticsearch 在解析 repository metadata 时，遇到了当前上下文不支持的字段名。根据日志片段，这一层能识别的通常只有 uuid、type、settings、generation 等固定字段；如果 … - [读取搜索请求时要求字段内全部为字符串值 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-read-search-request-expected-string-values-in-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.x-8.x 1. 问题含义 # could not read search request. expected string values in [field] 表示 Elasticsearch 在解析搜索请求时，当前字段应当是“字符串数组”，但实际读到了非字符串元素。 这类异常常见于请求体中的 indices、routing、stored_fields 等列表字段被错误拼装， … - [过滤器初始化失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-initialse-filter-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.5 1. 错误异常的基本描述 # 过滤器初始化失败 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [重启后 term 尚未递增导致忽略 join – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/ignored-join-as-term-has-not-been-incremented-yet-after-reboot-how-to-solve-this-elasticsearch-exception/): 适用版本： 7-8.9 1. 错误异常的基本描述 # 重启后 term 尚未递增导致忽略 join 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [集群中恢复进程已在运行 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/restore-process-is-already-running-in-this-cluster-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.17 1. 错误异常的基本描述 # Restore process is already running in this cluster 表示你尝试发起新的快照恢复时，集群中已经存在一个活跃的 restore 过程。根据源码，在 7.0 之前的版本中，如果 RestoreInProgress 非空， … - [预期位置但发现了其他内容 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/expected-at-but-found-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # 预期位置但发现了其他内容 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [can only use elasticsearch-plugins.yml config file with distribution type docker - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/can-only-use-elasticsearch-plugins-yml-config-file-with-distribution-type-docker-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.16-8.3 1. 错误异常的基本描述 # can only use elasticsearch-plugins.yml config file with distribution type docker 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集 … - [can only use elasticsearch-plugins.yml config file with distribution type docker - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/can-only-use-elasticsearch-plugins.yml-config-file-with-distribution-type-docker-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.16-8.3 1. 错误异常的基本描述 # can only use elasticsearch-plugins.yml config file with distribution type docker 是 Elasticsearch 在启动阶段针对插件配置文件 elasticsearch-plugins.yml 的发行版校验异常。该错误表明当前 Elasticsearch … - [could not parse transform for watch unexpected field - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-transform-for-watch-unexpected-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # could not parse [TYPE] transform for watch [watchId]. unexpected field [field] 是 Elasticsearch Watcher 在解析某个 transform 时抛出的异常。此错误表示 transform 对象中出现当前 transform 类型不支持的字段。 … - [failed to load field [{}] - 字段值加载失败](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-load-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # failed to load field [{}] 来自字段读取逻辑。源码创建了 SingleFieldsVisitor，再调用 reader.accept(docId, visitor) 访问指定文档的字段；如果这里抛出 IOException，就会包装为 ElasticsearchParseException。 这不是查询语法错误， … - [failed to parse hipchat message, failed to parse field, expected a boolean value - 解析 HipChat 消息失败：字段类型不符合预期](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-hipchat-message-failed-to-parse-field-expected-a-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-6.8（HipChat 功能在更高版本中已废弃或移除） 1. 错误异常的基本描述 # failed to parse hipchat message. failed to parse [notify] field, expected a boolean value but found [VALUE_STRING] 表示 Elasticsearch Watcher … - [failed to parse repository [{}] - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-repository-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 注册快照仓库时，Elasticsearch 需要解析请求中的仓库定义，包括 type 和 settings。如果 JSON 结构不符合预期、字段位置错误，或者根本缺少 type，就会抛出 failed to parse repository [{}] 相关异常。 常见现象 # PUT /_snapshot/{repository} … - [JVM 监控刷新间隔配置](https://easysearch.cn/knowledge-base/easysearch_config/monitor.jvm.refresh_interval/): 配置项作用 # monitor.jvm.refresh_interval 配置项用于控制JVM 监控统计信息的刷新间隔时间。 此配置决定了 JvmService 多久刷新一次 JVM 统计信息（如内存使用、线程数、类加载等），避免频繁调用 JVM 接口获取数据。 配置项属性 # 配置路径: monitor.jvm.refresh_interval 数据类型: TimeValue（时间值） 默 … - [Meta值不能超过50个字符但实际超出——如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/meta-values-can-t-be-longer-than-50-chars-but-got-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.6-7.15 1. 错误异常的基本描述 # Meta值不能超过50个字符但实际超出— 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [SAML 对象类型不正确，期望类型但实际为其他类型 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/saml-object-is-incorrect-type-expected-but-was-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.7-8.9 1. 错误异常的基本描述 # SAML 对象类型不正确，期望类型但实际为其他类型 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Span or 查询不支持 currentFieldName - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/span-or-query-does-not-support-currentfieldname-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Span or 查询不支持 currentFieldName 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [SSLContext 初始化失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-initialize-the-sslcontext-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # SSLContext 初始化失败 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Unsupported url protocol protocol from URL url - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unsupported-url-protocol-protocol-from-url-url-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # Unsupported url protocol protocol from URL url 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引 … - [watch 的 input 必须是对象 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-input-for-watch-expected-an-object-representing-the-input-but-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.x 1. 错误异常的基本描述 # could not parse input for watch [id]. expected an object representing the input; but found [token] instead 表示 Watcher 在读取整个 input 节点时，期望得到一个 JSON 对象，但实际拿到的是字符串、数组、数字、布尔值 … - [加入集群重试延迟配置](https://easysearch.cn/knowledge-base/easysearch_config/discovery.zen.join_retry_delay/): 配置项作用 # discovery.zen.join_retry_delay 配置项用于控制节点加入集群失败后，下一次重试前的等待时间。 当节点尝试加入集群但遇到可重试的错误（如 NotMasterException）时，系统会等待此配置指定的时间后才进行下一次重试。 配置项属性 # 配置路径: discovery.zen.join_retry_delay 数据类型: TimeValue（时 … - [动态模板名称定义了运行时字段但类型不匹配——如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/dynamic-template-name-defines-a-runtime-field-but-type-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.11-7.15 1. 错误异常的基本描述 # Dynamic template [name] defines a runtime field but type [type] is not supported as runtime field 是 Elasticsearch 在解析动态模板（dynamic_templates）定义时抛出的映射解析异常。该错误表明：在动态模板中声明 … - [在所有重试后仍无法检索配置文件 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-retrieving-profile-after-all-retries-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.2-8.9 1. 错误异常的基本描述 # 在所有重试后仍无法检索配置文件 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [在重建索引过程中遇到批量失败 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/encountered-bulk-failures-during-reindex-process-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.5-8.9 1. 错误异常的基本描述 # 在重建索引过程中遇到批量失败 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [搜索上下文丢失 (search_context_missing_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/search_context_missing_exception/): 为什么这个错误发生 # search_context_missing_exception 表示搜索上下文不存在，通常发生在使用 scroll 时上下文已过期。 如何修复 # 1. 重新执行搜索 # POST /<index>/_search?scroll=1m { "size": 100, "query": { … - [数据库文件 databaseFile 不存在 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/database-file-databasefile-doesn-t-exist-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.13-8.11 1. 错误异常的基本描述 # 数据库文件 databaseFile 不存在 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [文件系统健康检查启用配置](https://easysearch.cn/knowledge-base/easysearch_config/monitor.fs.health.enabled/): 配置项作用 # monitor.fs.health.enabled 配置项用于控制是否启用文件系统健康检查服务。 启用后，系统会定期在数据路径上创建和删除临时文件，检查文件系统的写入能力和同步（fsync）操作是否正常，同时监控 IO 操作的性能。 配置项属性 # 配置路径: monitor.fs.health.enabled 数据类型: Boolean（布尔值） 默认值: true 是否可 … - [无法为排序 key 解析比较器 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-resolve-comparator-for-sort-key-sort-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # 这个异常说明 Elasticsearch 在某个需要排序的上下文里，拿到了一个无法映射成合法比较器的 sort 值。常见场景包括 suggestion、term/phrase 相关排序选项或其他内部排序键解析。 2. 为什么会发生这个错误 # 从保留的上下文看，请求中存在： "sort": … - [无法关闭数据生命周期服务 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unable-to-close-the-data-lifecycle-service-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.8-8.9 1. 错误异常的基本描述 # 无法关闭数据生命周期服务 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法检测热点线程 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-detect-hot-threads-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 无法检测热点线程 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法解析影响因子（Influencer）– 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-influencer-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 无法解析影响因子（Influencer） 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [期望 EMPTY 或 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/expected-empty-or-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # 期望 EMPTY 或 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [未找到指定ID的模型部署 – 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/no-known-model-deployment-with-id-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.8-8.9 1. 错误异常的基本描述 # 未找到指定ID的模型部署 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [查询许可证](https://easysearch.cn/knowledge-base/easysearch_api/get-license/): 此 API 用于获取 Easysearch 的许可证信息。 API # GET /_license GET /_license/info API 的作用 # 返回 Easysearch 集群的许可证信息，包括： 许可证类型：许可证的类型（如 basic、platinum、enterprise） 许可证 ID：许可证的唯一标识符 颁发给：许可证颁发给的实体 颁发日期：许可证的颁发时间 有效期： … - [磁盘阈值分配控制配置](https://easysearch.cn/knowledge-base/easysearch_config/cluster.routing.allocation.disk.threshold_enabled/): 配置项作用 # cluster.routing.allocation.disk.threshold_enabled 配置项控制是否启用基于磁盘使用率的分片分配策略。启用后，集群会根据各节点的磁盘使用情况，自动决定是否向该节点分配新的分片，防止磁盘空间不足导致节点故障。 配置项类型 # 该配置项为动态配置，可以在运行时通过集群设置 API 进行修改。 默认值 # true（启用磁盘阈值检查） … - [管理索引别名](https://easysearch.cn/knowledge-base/easysearch_api/manage-index-alias/): 批量执行索引别名操作，在单个请求中完成多个别名的添加、删除或索引删除操作。 API # POST /_aliases API 的作用 # 该 API 允许在单个原子操作中执行多个别名相关的操作： 操作类型 描述 add 为索引添加别名 remove 从索引删除别名 remove_index 删除索引及其所有别名 使用场景 # 场景 描述 零停机重建 … - [索引管理外部角色过滤配置](https://easysearch.cn/knowledge-base/easysearch_config/plugins.index_management.filter_by_external_roles/): 配置项作用 # plugins.index_management.filter_by_external_roles 配置项用于控制是否根据用户的后端角色过滤索引管理（ISM）资源的访问。 索引管理包括策略（Policies）、转换（Transforms）、汇总（Rollups）等资源。当启用此配置时，用户只能访问其后端角色与资源存储的后端角色有交集的资源。这为多租户环境提供了基于角色的访问控制。 … - [网关期望节点数配置](https://easysearch.cn/knowledge-base/easysearch_config/gateway.expected_nodes/): 配置项作用 # gateway.expected_nodes 配置项指定集群恢复时期望的节点数量。当集群重启时，此配置控制必须有多少个节点加入后才开始恢复集群状态。 配置项类型 # 该配置项为静态配置，需要在启动时设置，修改后需要重启节点才能生效。 默认值 # -1（禁用此检查） 是否必需 # 可选配置项（已弃用） 取值范围 # -1 ~ 正整数 配置格式 # # 禁用（默认） … - [节点断开连接 (node_disconnected_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/node_disconnected_exception/): 为什么这个错误发生 # node_disconnected_exception 表示与集群中的某个节点的连接已断开。这通常发生在节点间通信过程中。 这个错误可能由以下原因引起： 节点宕机：目标节点进程崩溃或服务器故障 网络问题：节点间的网络连接中断 节点关闭：节点正在被正常关闭 连接超时：节点响应时间过长导致连接超时 防火墙阻断：防火墙规则阻止了节点间通信 高负载： … - [解析存储库失败，期望对象 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-repository-expected-object-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # failed to parse repository [{}]; expected object 表示 Elasticsearch 在逐个解析 repository 条目时，预期读到一个对象结构，例如 { "type": "fs", "settings": {...} }，但实 … - [6.0.0及以上版本不允许使用include_in_all参数——如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/include-in-all-is-not-allowed-for-indices-created-on-or-after-version-6.0.0-as-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-6.8 1. 错误异常的基本描述 # 6.0.0及以上版本不允许使用include_in_all参数— 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [cannot delete model as it is still referenced by ingest processors - 模型仍被 Ingest Processor 引用无法删除如何解决](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-delete-model-as-it-is-still-referenced-by-ingest-processors-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.6-7.15 1. 错误异常的基本描述 # Cannot delete model [model_id] as it is still referenced by ingest processors 表示在 Elasticsearch 中删除训练模型（Trained Model）时，该模型仍被一个或多个 Ingest Pipeline 中的处理器（如 inference … - [IndexShard 不允许读取 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/read-not-allowed-on-indexshard-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.16-8.9 1. 错误异常的基本描述 # IndexShard 不允许读取 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [More like this 需要指定 like 参数 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/more-like-this-requires-like-to-be-specified-how-to-solve-this-elasticsearch-exception/): 适用版本： Elasticsearch 5.x、6.x、7.x、8.x（全版本均适用） 影响版本说明： 该错误自 more_like_this 查询引入以来即存在，各版本报错信息一致，仅在异常类名上有细微差异（7.x 前后由 ParsingException 统一处理）。 1. 错误异常的基本描述 # more_like_this requires 'like' to be specified … - [Percolate 查询无法执行时 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/percolate-queries-cannot-be-executed-when-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.7-7.15 1. 错误异常的基本描述 # Percolate 查询无法执行时 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Pipeline ID 不能定义空的 on_failure 选项 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/pipeline-id-cannot-have-an-empty-on-failure-option-defined-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Pipeline ID 不能定义空的 on_failure 选项 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Rollup 搜索最大数量配置](https://easysearch.cn/knowledge-base/easysearch_config/rollup.search.max_count/): 配置项作用 # rollup.search.max_count 配置项用于控制Rollup 搜索时的最大任务数量。 该配置定义了在执行 Rollup 搜索时最多可以搜索多少个 Rollup 任务，用于限制搜索范围，防止查询过多的 Rollup 索引导致性能问题。 配置项属性 # 配置路径: rollup.search.max_count 数据类型: Integer（整数） 默认值: 2 是否 … - [Search 线程池最小队列大小配置](https://easysearch.cn/knowledge-base/easysearch_config/thread_pool.search.min_queue_size/): 配置项作用 # thread_pool.search.min_queue_size 配置项用于控制搜索线程池队列的最小容量。 这是自动调整队列大小时的下限。 配置项属性 # 配置路径: thread_pool.search.min_queue_size 数据类型: Integer（整数） 默认值: 1000 是否可选: 是 作用域: NodeScope（节点级别） 动态更新: 否（已废弃） … - [SimpleQueryStringBuilder NAME 分析器未找到 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/simplequerystringbuilder-name-analyzer-analyzer-not-found-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.16-8.9 1. 错误异常的基本描述 # SimpleQueryStringBuilder NAME 分析器未找到 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见 … - [Transform 断路器 JVM 内存阈值配置](https://easysearch.cn/knowledge-base/easysearch_config/transform.circuit_breaker.jvm.threshold/): 配置项作用 # transform.circuit_breaker.jvm.threshold 配置项用于控制Transform 断路器的 JVM 内存使用阈值。 当 JVM 堆内存使用率超过此值时，Transform 任务将被阻止执行。 配置项属性 # 配置路径: transform.circuit_breaker.jvm.threshold 数据类型: Integer（整数，百分比） 默 … - [Transform任务未完全初始化 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/task-for-transform-not-fully-initialized-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.4-7.5 1. 错误异常的基本描述 # Transform任务未完全初始化 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Transport TCP No Delay 配置](https://easysearch.cn/knowledge-base/easysearch_config/transport.tcp_no_delay/): 配置项作用 # transport.tcp_no_delay 配置项用于控制是否禁用 Nagle 算法（启用 TCP_NODELAY 选项）。 配置项属性 # 配置路径: transport.tcp_no_delay 数据类型: Boolean（布尔值） 默认值: true 是否可选: 是 作用域: NodeScope（节点级别） 动态更新: 否（需要重启节点生效） 废弃状态: 已废弃，建议 … - [从响应中提取主体时出错 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/error-extracting-body-from-response-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 从响应中提取主体时出错 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [分片不活跃时间配置](https://easysearch.cn/knowledge-base/easysearch_config/indices.memory.shard_inactive_time/): 配置项作用 # indices.memory.shard_inactive_time 配置项控制判定分片不活跃的时间阈值。当分片在指定时间内没有索引操作时，系统将其标记为不活跃，并可以释放其索引缓冲区内存，用于其他活跃分片。 配置项类型 # 该配置项为静态配置，需要在启动时设置，修改后需要重启节点才能生效。 默认值 # 5m 是否必需 # 可选配置项（有默认值） 取值范围 # 0 ~ 正 … - [分配未路由到节点 – 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/assignment-with-id-is-not-routed-to-node-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.17-8.9 1. 错误说明 # assignment with id is not routed to node 是 Elasticsearch 在机器学习模型部署（Model Deployment）场景下抛出的异常。当客户端尝试对某个已部署的模型执行更新、停止或管理操作时，Elasticsearch 会先校验该部署任务（deploymentId）是否已路由到目标节 … - [创建令牌文档失败 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-create-token-document-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # 创建令牌文档失败 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [删除摄入管道](https://easysearch.cn/knowledge-base/easysearch_api/delete-ingest-pipeline/): 从集群中删除指定的摄入管道。 API 格式 # DELETE /_ingest/pipeline/{id} API 作用 # 该 API 用于从集群中删除摄入管道： 删除指定 ID 的摄入管道 支持使用通配符批量删除多个管道 删除后无法用于文档预处理 API 参数 # 路径参数 # 参数 类型 是否必填 默认值 描述 {id} String 是 - 管道 ID，支持通配符 … - [刷新失败 (refresh_failed_engine_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/refresh_failed_engine_exception/): 为什么这个错误发生 # refresh_failed_engine_exception 表示将更改刷新到搜索索引时失败。 如何修复 # 1. 检查磁盘空间 # df -h 2. 重启分片 # POST /_cluster/reroute?retry_failed=true 3. 调整刷新间隔 # PUT /<index>/_settings { … - [字段 fieldName 不支持 ShapeType LINESTRING 查询 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/field-fieldname-does-not-support-shapetype-linestring-queries-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.16-8.9 1. 错误异常的基本描述 # 字段 fieldName 不支持 ShapeType LINESTRING 查询 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判 … - [存储位置 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/store-location-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.13 1. 错误异常的基本描述 # 存储位置 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [当设置搜索分析器时必须为字段设置分析器 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/analyzer-on-field-name-must-be-set-when-search-analyzer-is-set-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.17，8.x 及以上版本行为类似 1. 错误异常的基本描述 # analyzer on field [xxx] must be set when search_analyzer is set 是 Elasticsearch 在索引映射（mapping）定义阶段抛出的 MapperParsingException 异常。该错误表明： … - [意外的IP范围参数parser currentName – 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unexpected-ip-range-parameter-parser-currentname-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 意外的IP范围参数parser currentName 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可 … - [数值字段必须同时设置这两个参数 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/both-and-must-be-set-for-numeric-fields-how-to-solve-this-elasticsearch-exception/): 适用版本： 5.x-8.x 1. 错误异常的基本描述 # both [scale] and [origin] must be set for numeric fields 是 Elasticsearch 在使用**衰减函数（Decay Function）**查询数值类型字段时抛出的参数校验异常。该错误表明：在构造 gauss、exp 或 linear 衰减函数时， … - [无效的索引名称 (invalid_index_name_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/invalid_index_name_exception/): 为什么这个错误发生 # invalid_index_name_exception 表示使用的索引名称不符合 Easysearch 的命名规则或包含非法字符。 这个错误可能由以下原因引起： 非法字符：索引名包含不允许的字符 以特殊字符开头：索引名以 -、_ 或 + 开头 大写字母：索引名包含大写字母（必须全小写） 空名称：索引名为空 名称过长：索引名超过 255 字节 包含空格：索引名包含空格字 … - [无法找到分片 shardId 的最新快照 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unable-to-find-the-latest-snapshot-for-shard-shardid-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.15-8.9 1. 错误异常的基本描述 # Unable to find the latest snapshot for shard [shardId] 表示 Elasticsearch 在恢复或查找分片快照信息时，试图为某个分片定位“最新可用快照”，但这一定位过程失败，于是包装成 RepositoryException 返回。 它比“读取 shard snapshot … - [无法终止指定版本节点上的进程 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-kill-the-process-on-node-with-version-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-6.8 1. 错误异常的基本描述 # 无法终止指定版本节点上的进程 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法解析监视器条件，期望比较字段或比较量词字段（Could not parse condition for watch. expected a field indicating the comparison value or comparison quantifier）- 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-condition-for-watch-expected-a-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.x 1. 错误异常的基本描述 # could not parse [compare] condition for watch [...]. expected a field indicating the comparison value or comparison quantifier; but found [...] instead 表示 Watcher … - [无法计算字段权限 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unable-to-compute-field-permissions-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 无法计算字段权限 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法读取分片快照文件 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-read-shard-snapshot-file-for-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.3 1. 错误异常的基本描述 # failed to read shard snapshot file for [shardId] 表示 Elasticsearch 已经定位到具体分片的快照文件，但在通过 indexShardSnapshotFormat.read(...) 读取 shard 级 snapshot 元数据时抛出 IOException， … - [时间序列聚合不能在全局聚合中使用 – 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/time-series-aggregations-cannot-be-used-inside-global-aggregation-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.1-8.9 1. 错误异常的基本描述 # 时间序列聚合不能在全局聚合中使用 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [未知的 map reducer - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unknown-map-reducer-mapreducername-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.4-8.9 1. 错误异常的基本描述 # Unknown map reducer [mapReducerName] 表示节点在反序列化聚合结果时，读到了一个自己不认识的 map reducer 名称，因此无法继续还原 frequent_item_sets 相关聚合结果。 这不是普通 DSL 拼写错误。根据当前页面保留的源码，它发生在内部聚合结果从流中读取的阶段，说明 写出结果的 … - [查询缓存配置](https://easysearch.cn/knowledge-base/easysearch_config/indices.queries.cache.size/): 配置项作用 # indices.queries.cache.size 配置项控制查询缓存（Query Cache）的 JVM 堆内存大小。查询缓存用于缓存查询结果，提高重复查询的性能。 配置项类型 # 该配置项为动态配置，可以在运行时通过集群设置 API 进行修改。 默认值 # 10%（JVM 堆内存的 10%） 是否必需 # 可选配置项（有默认值） 配置格式 # # 百分比格式（默认） … - [策略未找到——如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/policy-not-found-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.5-8.9 1. 错误异常的基本描述 # 策略未找到— 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [管理传统索引模板](https://easysearch.cn/knowledge-base/easysearch_api/manage-legacy-index-template/): 创建、获取、删除传统索引模板（Legacy Index Templates）。 API # POST /_template/{name} PUT /_template/{name} GET /_template GET /_template/{name} DELETE /_template/{name} API 的作用 # 传统索引模板允许您定义在创建新索引时自动应用的设置、映射和别名。 注 … - [索引模板匹配请求名称未找到 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/index-template-matching-request-name-not-found-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.8-8.9 1. 错误异常的基本描述 # 索引模板匹配请求名称未找到 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [[NAME] 必填字段 field 缺失 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/name-required-field-field-missing-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.x 1. 错误说明 # [NAME] required field 'field' missing 是 Elasticsearch 在解析 DSL 请求时抛出的 ParsingException。当某个查询构建器（如 field_value_factor）要求必须提供 field 参数，但请求体中未包含该字段时，Elasticsearch 会在请求解析阶段直接拒绝整个查 … - [Function score 查询返回无效分数 finalScore for doc – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/function-score-query-returned-an-invalid-score-finalscore-for-doc-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Function score 查询返回无效分数 finalScore for doc 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判 … - [geometries 参数不支持该类型 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/parameter-geometries-is-not-supported-for-type-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.2-8.9 1. 错误异常的基本描述 # geometries 参数不支持该类型 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [HTTP request template 的时间字段无效 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-http-request-template-invalid-time-value-for-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # could not parse http request template. invalid time value for [field] field 是 Elasticsearch Watcher 在解析 HTTP request template 时抛出的异常， … - [Listener 线程池队列大小配置](https://easysearch.cn/knowledge-base/easysearch_config/thread_pool.listener.queue_size/): 配置项作用 # thread_pool.listener.queue_size 配置项用于控制监听器线程池的队列大小。 配置项属性 # 配置路径: thread_pool.listener.queue_size 数据类型: Integer（整数） 默认值: -1（无界队列） 是否可选: 是 作用域: NodeScope（节点级别） 动态更新: 是（可以动态更新，无需重启） 废弃状态: … - [Span not include must be of type span query - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/span-not-include-must-be-of-type-span-query-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Span not include must be of type span query 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起 … - [Transport Netty Boss 线程数配置](https://easysearch.cn/knowledge-base/easysearch_config/transport.netty.boss_count/): 配置项作用 # transport.netty.boss_count 配置项用于控制Netty 服务器中 Boss 线程的数量。 Boss 线程负责接受新的连接请求并将它们分派给 Worker 线程。 配置项属性 # 配置路径: transport.netty.boss_count 数据类型: Integer（整数） 默认值: 1 是否可选: 是 作用域: NodeScope（节点级别） 动 … - [Unknown key for index template - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unknown-key-for-index-template-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # unknown key for index template 是 Elasticsearch 在解析索引模板（Index Template）定义时抛出的 ElasticsearchParseException 异常。当模板 JSON/YAML 中包含 Elasticsearch 无法识别的配置键时，解析器无法继续处理模板定义，从而抛出此 … - [Unknown license version found - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unknown-license-version-found-please-upgrade-all-nodes-to-the-latest-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # Unknown license version found; please upgrade all nodes to the latest elasticsearch-license plugin 表示集群中某些节点的许可证插件版本低于许可证本身的版本。 从源码可见，这个异常在许可证解析路径中抛出，当许可证版本号大于当前节点支持的最大 … - [WKT 边界框解析失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-wkt-bounding-box-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.6-8.9 1. 错误异常的基本描述 # failed to parse WKT bounding box 是 Elasticsearch 在执行地理边界框查询（geo_bounding_box）时抛出的解析异常。当请求中以 WKT（Well-Known Text）字符串形式传入边界框几何对象，而 Elasticsearch 无法将其正确解析为矩形边界框时，就会触发此错误。 常 … - [任务未找到 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/task-is-not-found-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.8-8.9 1. 错误异常的基本描述 # 任务未找到 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返回 400、404、409、429、500 … - [传输层连接超时配置](https://easysearch.cn/knowledge-base/easysearch_config/transport.connect_timeout/): 配置项作用 # transport.connect_timeout 配置项控制传输层客户端连接到其他节点的超时时间。当节点尝试连接到集群中的其他节点时，如果在此时间内未能建立连接，连接尝试将失败。此配置是已弃用的 transport.tcp.connect_timeout 配置的新名称。 配置项类型 # 该配置项为静态配置，需要在启动时设置，修改后需要重启节点才能生效。 默认值 # 30s … - [使用选定安全提供程序的 PBKDF2 实现时出错 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/error-using-pbkdf2-implementation-from-the-selected-security-provider-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.11-8.9 1. 错误异常的基本描述 # 使用选定安全提供程序的 PBKDF2 实现时出错 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [删除point-in-time](https://easysearch.cn/knowledge-base/easysearch_api/delete-point-in-time/): 此 API 用于删除 Point In Time (PIT) 搜索上下文，释放集群资源。建议在完成搜索后及时删除不再使用的 PIT。 API # DELETE /_pit DELETE /_pit/_all API 的作用 # 删除 PIT 上下文，主要用途包括： 释放资源：删除不再使用的 PIT，释放内存和计算资源 批量清理：删除所有 PIT 上下文 精确管理：删除指定的 PIT … - [同义词集 resourceName 未找到 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/synonym-set-resourcename-not-found-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.9-8.9 1. 错误异常的基本描述 # 同义词集 resourceName 未找到 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [字段 fieldName 不支持 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/field-fieldname-does-not-support-how-to-solve-this-elasticsearch-exception/): 适用版本： 7-7.15 1. 错误异常的基本描述 # 字段 fieldName 不支持 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [字段 fieldName 发现不支持的形状 LinearRing – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/field-fieldname-found-and-unsupported-shape-linearring-how-to-solve-this-elasticsearch-exception/): 适用版本： 7-7.6 1. 错误异常的基本描述 # 字段 fieldName 发现不支持的形状 LinearRing 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [对象映射 parentMapper 尝试序列化一个值时出现错误 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/object-mapping-parentmapper-name-trying-to-serialize-a-value-with-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # 对象映射 parentMapper 尝试序列化一个值时出现错误 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [恢复引擎异常 (recovery_engine_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/recovery_engine_exception/): 为什么这个错误发生 # recovery_engine_exception 表示在分片恢复过程中的引擎阶段失败。恢复引擎负责将分片恢复到一致状态，包括事务日志和索引文件的恢复。 这个错误可能由以下原因引起： 事务日志损坏：事务日志文件损坏无法恢复 索引文件损坏：Lucene 索引文件损坏 检查点不匹配：检查点信息不匹配 恢复阶段失败：特定恢复阶段（Phase 1-4）执行失败 磁盘 IO 错 … - [我们只支持基于数字字段的AVG、MEDIAN和SUM](https://easysearch.cn/knowledge-base/elasticsearch_error/we-only-support-avg-median-and-sum-on-number-based-fields-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 我们只支持基于数字字段的AVG、MEDIAN和SUM 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能 … - [无效的Unicode字符代码是代理代码——如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/invalid-unicode-character-code-is-a-surrogate-code-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.13-8.9 1. 错误异常的基本描述 # 无效的Unicode字符代码是代理代码— 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法查找评分 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/couldn-t-lookup-score-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # 无法查找评分 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法解析时间单位 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-time-unit-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # failed to parse time unit 是 Elasticsearch 在解析时间字符串时抛出的底层异常，表示传入的时间值无法被正确识别为合法的 TimeValue。该错误通常出现在需要时间参数的配置中，例如 Watcher 定时任务、索引生命周期管理（ILM）、超时设置、重试间隔等场景。 Elasticsearch 内部 … - [无法解析索引的 query 字段 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-field-query-for-indices-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.5-7.15 1. 错误异常的基本描述 # 无法解析索引的 query 字段 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [期望数据节点数配置](https://easysearch.cn/knowledge-base/easysearch_config/gateway.expected_data_nodes/): 配置项作用 # gateway.expected_data_nodes 配置项指定集群启动恢复前期望的数据节点数量。集群会等待直到达到指定数量的数据节点才开始恢复。 是否可选 # 是 默认值 # -1 (不设置期望) 配置项类型 # 静态配置 - 需要重启节点才能生效 配置格式 # # 默认配置（不设置期望） gateway.expected_data_nodes: -1 # 指定期望节 … - [本地发布的集群状态既没有元数据也没有路由表 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cluster-state-that-is-published-locally-has-neither-how-to-solve-this-elasticsearch-exception/): 适用版本： 7-7.15 1. 错误异常的基本描述 # 本地发布的集群状态既没有元数据也没有路由表 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [管理索引模板](https://easysearch.cn/knowledge-base/easysearch_api/manage-index-template/): 创建、获取、删除可组合索引模板（Composable Index Templates）。 API # PUT /_index_template/{name} POST /_index_template/{name} GET /_index_template GET /_index_template/{name} DELETE /_index_template/{name} API 的作用 # … - [缺少 URL – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/missing-url-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 缺少 URL 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [节点级写入限流启用配置](https://easysearch.cn/knowledge-base/easysearch_config/cluster.throttle.node.write/): 配置项作用 # cluster.throttle.node.write 配置项控制是否启用节点级别的写入限流功能。 默认值 # false 配置类型 # 动态配置 配置格式 # # 启用节点级写入限流 cluster.throttle.node.write: true # 禁用（默认） cluster.throttle.node.write: false 使用场景 # 启用节点级限流可 … - [获取连接失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-acquire-connection-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.16-8.9 1. 错误异常的基本描述 # 获取连接失败 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返回 400、404、409、429、500 … - [设置必须为非负数 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/setting-must-be-non-negative-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.12-8.9 1. 错误异常的基本描述 # 设置必须为非负数 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [集群状态版本不兼容 (incompatible_cluster_state_version_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/incompatible_cluster_state_version_exception/): 为什么这个错误发生 # incompatible_cluster_state_version_exception 表示集群状态的版本与预期不匹配。集群状态有一个版本号和 UUID，当节点尝试应用集群状态更新时，如果版本号或 UUID 不匹配，就会抛出此异常。 这个错误可能由以下原因引起： 版本落后：节点的集群状态版本落后于主节点的版本 集群分裂：网络分区导致集群分裂成多个独立子集群 主节点切 … - [页面缓存int[] 类型页面的权重配置](https://easysearch.cn/knowledge-base/easysearch_config/cache.recycler.page.weight.ints/): 配置项作用 # cache.recycler.page.weight.ints 配置项控制 ints 类型页面在页面缓存中的内存分配权重。 默认值 # 配置类型 # 静态配置 取值范围 # 配置格式 # # 默认配置 cache.recycler.page.weight.ints: 1.0 # 增加权重 cache.recycler.page.weight.ints: 2.0 - [Header cannot be overwritten via fullSetting – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/header-cannot-be-overwritten-via-fullsetting-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.6-8.9 1. 错误异常的基本描述 # Header cannot be overwritten via fullSetting 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一 … - [ISM 协调器重试间隔配置](https://easysearch.cn/knowledge-base/easysearch_config/index_state_management.coordinator.backoff_millis/): 配置项作用 # index_state_management.coordinator.backoff_millis 配置项用于控制索引状态管理（ISM）协调器在操作失败后重试之前的等待时间。 当协调器执行批量操作失败时（如遇到 429 Too Many Requests 错误），系统会等待此配置指定的时间后进行重试。 配置项属性 # 配置路径: … - [OpenID Connect Provider 响应指示身份验证失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/openid-connect-provider-response-indicates-authentication-failure-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.2-7.15 1. 错误异常的基本描述 # OpenID Connect Provider 响应指示身份验证失败 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [SSL KeyManagerFactory 初始化失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-initialize-ssl-keymanagerfactory-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # SSL KeyManagerFactory 初始化失败 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能 … - [Transport 绑定主机配置](https://easysearch.cn/knowledge-base/easysearch_config/transport.bind_host/): 配置项作用 # transport.bind_host 配置项用于控制Easysearch 节点绑定的网络接口地址。 配置项属性 # 配置路径: transport.bind_host 数据类型: List<String>（字符串列表） 默认值: 继承自 network.host，默认为 _local_（仅环回） 是否可选: 是 作用域: NodeScope（节点级别） 动态更 … - [Type type cannot be used in multi field – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/type-type-cannot-be-used-in-multi-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Type type cannot be used in multi field 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 … - [URL 仓库地址配置](https://easysearch.cn/knowledge-base/easysearch_config/repositories.url.url/): 配置项作用 # repositories.url.url 配置项用于定义 URL 仓库的根地址。 配置项属性 # 配置路径: repositories.url.url 数据类型: URL（URL 对象） 默认值: "http:"（默认使用 http 协议） 是否可选: 否（URL 仓库必须配置） 作用域: NodeScope（节点级别） 动态更新: 是（可以动态更新，无需 … - [严格动态映射异常 (strict_dynamic_mapping_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/strict_dynamic_mapping_exception/): 为什么这个错误发生 # strict_dynamic_mapping_exception 表示索引映射配置为严格模式（strict dynamic mapping），尝试动态引入新字段时被拒绝。 如何修复 # 1. 关闭严格模式 # # 更新索引设置 PUT /<index>/_settings { "index.mapper.dynamic": … - [同主机分片分配限制配置](https://easysearch.cn/knowledge-base/easysearch_config/cluster.routing.allocation.same_shard.host/): 配置项作用 # cluster.routing.allocation.same_shard.host 配置项控制是否允许同一分片的不同副本分配到同一主机的不同节点上。启用此配置后，系统会根据主机名或主机地址检查，防止同一分片的主分片和副本分片部署在同一物理主机上。 配置项类型 # 该配置项为动态配置，可以在运行时通过集群设置 API 进行修改。 默认值 # false（不检查，允许同主机分 … - [字段掩码span查询必须是span类型 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/field-masking-span-query-must-be-of-type-span-query-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.14 1. 错误异常的基本描述 # 字段掩码span查询必须是span类型 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [字段掩码跨度必须为其设置字段 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/field-masking-span-must-have-field-set-for-it-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.14 1. 错误异常的基本描述 # 字段掩码跨度必须为其设置字段 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [字段的时间值无效 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/invalid-time-value-for-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 字段的时间值无效 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [尝试对失败的转换执行批量索引 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/attempted-to-do-a-bulk-index-request-for-failed-transform-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.4-8.9 1. 错误异常的基本描述 # attempted to do a bulk index request for failed transform 是 Elasticsearch Transform（数据转换）功能中一种保护性异常。当某个 Transform 任务已经进入 FAILED 状态后，系统仍尝试对其执行批量索引写入操作时，就会触发该异常。 该异常的核心含义 … - [必须为其设置字段 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/must-have-field-set-for-it-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.15-8.9 1. 错误异常的基本描述 # 必须为其设置字段 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [数据流 Arrays.toString(request.getNames()) 未找到 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/data-streams-arrays-tostring-request-getnames-not-found-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.9-8.11 1. 错误异常的基本描述 # 数据流 Arrays.toString(request.getNames()) 未找到 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判 … - [无效的源类型 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/invalid-source-type-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # 无效的源类型 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法从非主节点刷新告警 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-refresh-alerts-from-nodes-other-than-currently-elected-master-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.11-8.9 1. 错误异常的基本描述 # 无法从非主节点刷新告警 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法停止数据框转换 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unable-to-stop-data-frame-transform-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.2-7.2 1. 错误异常的基本描述 # 无法停止数据框转换 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法删除不兼容的快照 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-delete-incompatible-snapshot-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.3 1. 错误异常的基本描述 # cannot delete incompatible snapshot 表示你要删除的快照在仓库元数据里被归类为 incompatibleSnapshotIds，也就是当前集群版本无法正常理解或安全处理它的快照元数据，因此删除流程在真正执行前就被阻止，并抛出 SnapshotException。 这不是普通的“快照不存在”，也不是仓库只 … - [无法构建有效的分词结果 – 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/no-valid-tokenization-to-build-result-how-to-solve-this-elasticsearch-exception/): 适用版本： 8-8.9 1. 错误异常的基本描述 # 无法构建有效的分词结果 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法解释文档 hitContext.hit().getType() – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-explain-doc-hitcontext-hit-gettype-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.9 1. 错误异常的基本描述 # 无法解释文档 hitContext.hit().getType() 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [未知的 URL 协议 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unknown-url-protocol-from-url-urltocheck-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.16-8.9 1. 错误异常的基本描述 # 未知的 URL 协议 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [未知的触发器类型 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unknown-trigger-type-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 未知的触发器类型 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [查询索引模板（Cat格式）](https://easysearch.cn/knowledge-base/easysearch_api/get-index-template-cat-format/): 以紧凑的表格形式返回集群中的索引模板信息。 API 格式 # GET /_cat/templates GET /_cat/templates/{name} API 作用 # 该 API 以表格形式返回索引模板信息： 显示所有模板或匹配指定名称的模板 支持 v1 和 v2 索引模板 显示模板的索引模式、优先级、组件等信息 API 参数 # 路径参数 # … - [模糊查询无法执行时 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/fuzzy-queries-cannot-be-executed-when-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.7-7.15 1. 错误异常的基本描述 # 模糊查询无法执行时 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [父字段在单类型索引上已禁用 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/parent-field-is-disabled-on-indices-with-a-single-type-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-6.8 1. 错误异常的基本描述 # 父字段在单类型索引上已禁用 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [解压缩 source 失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-decompress-source-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.x 1. 错误异常的基本描述 # failed to decompress source 表示 Elasticsearch 在尝试读取某条文档的 _source 字段时，发现其存储的压缩字节流无法被正确解压。与普通 JSON 解析错误不同，这一步发生在更底层——Elasticsearch 甚至还没进入字段级反序列化阶段，问题就已经出现在 压缩后的原始字节流 上。 该异常 … - [设置更新在步骤 getKey toString 中未被确认 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/settings-update-not-acknowledged-in-step-getkey-tostring-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.12-8.6 1. 错误异常的基本描述 # 设置更新在步骤 getKey toString 中未被确认 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [阻塞操作在新的TimeValue超时timeUnit后超时 – 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/timeout-while-blocking-operations-after-new-timevalue-timeout-timeunit-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.7-8.9 1. 错误异常的基本描述 # 阻塞操作在新的TimeValue超时timeUnit后超时 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能 … - [集群只读块配置](https://easysearch.cn/knowledge-base/easysearch_config/cluster.blocks.read_only/): 配置项作用 # cluster.blocks.read_only 配置项控制整个集群的只读状态。当启用此配置后，集群中的所有索引将禁止写入操作和元数据修改操作，仅允许读取操作。此配置通常用于磁盘空间不足时自动保护数据，或手动设置以防止数据修改。 配置项类型 # 该配置项为动态配置，可以在运行时通过集群设置 API 进行修改。 默认值 # false（不启用只读块） 是否必需 # 可选配置 … - [集群重新路由](https://easysearch.cn/knowledge-base/easysearch_api/cluster-reroute/): 手动更改集群中单个分片（shard）的分配，允许管理员在特殊情况下手动干预分片分配策略。 API # POST /_cluster/reroute API 的作用 # 该 API 允许手动更改集群中分片的分配，可以用于： 移动分片（move）：将分片从一个节点移动到另一个节点 取消分配（cancel）：取消分片的重新定位或恢复 分配副本（allocate_replica）：将未分配的副本分片 … - [非法的分片状态 (illegal_index_shard_state_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/illegal_index_shard_state_exception/): 为什么这个错误发生 # illegal_index_shard_state_exception 表示分片处于不允许当前操作的状态。 如何修复 # 1. 检查分片状态 # GET /_cat/shards?v 2. 等待状态变更 # 分片可能正在恢复或迁移。 3. 重试操作 # 状态变化后重试。 预防措施 # 在分片稳定后执行操作 - [默认搜索超时配置](https://easysearch.cn/knowledge-base/easysearch_config/search.default_search_timeout/): 配置项作用 # search.default_search_timeout 配置项设置搜索请求的默认超时时间。当搜索请求中没有明确指定超时参数时，将使用此配置作为超时时间。超过此时间后，搜索请求将被取消并返回部分结果或超时错误。 配置项类型 # 该配置项为动态配置，可以在运行时通过集群设置 API 进行修改。 默认值 # 60s 是否必需 # 可选配置项（有默认值） 取值范围 # 时间格 … - [could not parse transform for watch failed to parse script - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-transform-for-watch-failed-to-parse-script-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # could not parse [TYPE] transform for watch [watchId]. failed to parse script 是 Elasticsearch Watcher 在解析 script transform（脚本转换）时抛出的异常。此错误表示脚本对象本身无法被正确解析。 问题通常出在 script 定 … - [ERROR 无法打开目录 indexPath 正在退出 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/error-could-not-open-directory-indexpath-exiting-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # ERROR 无法打开目录 indexPath 正在退出 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Hunspell 词典忽略大小写配置](https://easysearch.cn/knowledge-base/easysearch_config/indices.analysis.hunspell.dictionary.ignore_case/): 配置项作用 # indices.analysis.hunspell.dictionary.ignore_case 配置项控制 Hunspell 词典匹配时是否忽略大小写。启用后，相同单词的不同大小写形式将被视为同一单词。 默认值 # false（区分大小写） 配置类型 # 节点级配置 取值范围 # true：不区分大小写匹配 false：区分大小写匹配（默认） 配置格式 # # 对所 … - [Join target 未初始化 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/join-target-is-not-initialised-yet-how-to-solve-this-elasticsearch-exception/): 适用版本： 7-8.9 1. 错误异常的基本描述 # Join target 未初始化 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Runtime 必须是 map 类型 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/runtime-must-be-a-map-type-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.11-8.9 1. 错误异常的基本描述 # Runtime 必须是 map 类型 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Shape类型未包含 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/shape-type-not-included-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Shape类型未包含 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Span containing big 必须是 span query 类型 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/span-containing-big-must-be-of-type-span-query-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Span containing big 必须是 span query 类型 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见 … - [Span first 查询不支持 currentFieldName – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/span-first-query-does-not-support-currentfieldname-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Span first 查询不支持 currentFieldName 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Transport stopped action – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/transport-stopped-action-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.5 1. 错误异常的基本描述 # Transport stopped action 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [主对象后发现意外的标记](https://easysearch.cn/knowledge-base/elasticsearch_error/unexpected-token-token-found-after-the-main-object-how-to-solve-this-elasticsearch-exception/): 适用版本： 7-8.9 1. 错误异常的基本描述 # 主对象后发现意外的标记 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [准备事务日志目标失败 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/prepare-target-for-translog-failed-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 准备事务日志目标失败 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [发布意外失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/publishing-unexpectedly-failed-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.9-8.9 1. 错误异常的基本描述 # 发布意外失败 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [图形定义中的非法对象属性 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/illegal-object-property-in-graph-definition-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 图形定义中的非法对象属性 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [字段未找到normalizer normalizerName - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/normalizer-normalizername-not-found-for-field-name-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 字段未找到normalizer normalizerName 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [序列化数据框分析对象失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-serialise-data-frame-analytics-with-id-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.3-7.15 1. 错误异常的基本描述 # 序列化数据框分析对象失败 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [异步搜索结果最大保留时间](https://easysearch.cn/knowledge-base/easysearch_config/async_search.max_keep_alive/): 配置项作用 # async_search.max_keep_alive 配置项限制异步搜索结果在集群中存储的最长时间。该配置项是 keep_alive 参数的上限，用于防止异步搜索结果占用过多存储空间。 配置项类型 # 该配置项为动态配置，可以在运行时通过集群更新 API 进行修改，无需重启节点。 默认值 # 5d（5天） 是否必需 # 可选配置项 取值范围 # 正数时间值（ … - [无主节点发送分配悬挂索引请求——如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/no-master-to-send-allocate-dangled-request-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.17 1. 错误异常的基本描述 # 无主节点发送分配悬挂索引请求— 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法同步提交 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-sync-commit-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.17 1. 错误异常的基本描述 # 无法同步提交 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法解析 Model Snapshot - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-modelsnapshot-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 这个异常表示 Elasticsearch 在读取机器学习模型快照时，无法把存储的 JSON 内容解析回 ModelSnapshot 对象。根据附带源码，异常并不是出现在训练逻辑本身，而是出现在从字节流创建 XContentParser 并执行 LENIENT_PARSER.apply(...) 的阶段。 典型报错： failed to … - [无法解析响应体 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unable-to-parse-response-body-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 无法解析响应体 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法解析监视记录 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unable-to-parse-watch-record-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 无法解析监视记录 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [更多异常被丢弃 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/further-exceptions-were-dropped-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.7-8.9 1. 错误异常的基本描述 # 更多异常被丢弃 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [期望上下文映射的列表或条目 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/expected-a-list-or-an-entry-of-context-mapping-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 期望上下文映射的列表或条目 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [期望找到指定字段但未找到 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/expected-one-of-or-fields-but-found-none-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # 期望找到指定字段但未找到 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [查询插件](https://easysearch.cn/knowledge-base/easysearch_api/get-plugins/): 此 API 用于获取集群中所有节点上安装的插件信息。 API # GET /_cat/plugins API 的作用 # 返回集群中每个节点上安装的插件详细信息，包括： 节点信息：节点 ID 和节点名称 插件信息：插件组件名称、版本和描述 此 API 用于验证插件安装情况，确保所有节点上的插件版本一致，以及检查集群中安装了哪些插件。 API 的参数 # 此 API 没有路由参数。 查询字 … - [破坏性操作必须指定索引名配置](https://easysearch.cn/knowledge-base/easysearch_config/action.destructive_requires_name/): 配置项作用 # action.destructive_requires_name 配置项控制执行破坏性索引操作（如删除索引、关闭索引等）时，是否必须明确指定索引名称，禁止使用通配符（*）或 _all 等模糊匹配方式。 该配置项的目的是防止因误操作导致大量索引被意外删除或关闭，提高集群的安全性。 配置项类型 # 该配置项为动态配置，可以在运行时通过集群更新 API 进行修改，无需重启节点。 默认 … - [精度需要在0-9之间，收到的值超出范围 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/precision-needs-to-be-between-0-9-received-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # 精度需要在0-9之间，收到的值超出范围 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [索引状态管理启用配置](https://easysearch.cn/knowledge-base/easysearch_config/index_state_management.enabled/): 配置项作用 # index_state_management.enabled 配置项控制是否启用索引状态管理 (ISM) 功能。 是否可选 # 是 默认值 # true (启用 ISM) 配置项类型 # 动态配置 - 可以在运行时修改 配置格式 # # 启用 ISM（默认） index_state_management.enabled: true # 禁用 ISM … - [自动跟随获取轮询间隔配置](https://easysearch.cn/knowledge-base/easysearch_config/plugins.replication.autofollow.fetch_poll_interval/): 配置项作用 # plugins.replication.autofollow.fetch_poll_interval 配置项用于控制自动跟随任务轮询远程（Leader）集群检查新索引的间隔时间。 在跨集群复制（CCR）的自动跟随模式下，Follower 集群需要定期检查 Leader 集群是否有匹配自动跟随模式的新索引被创建。此配置决定了检查的频率。 配置项属性 # 配置路径: … - [获取索引别名](https://easysearch.cn/knowledge-base/easysearch_api/get-index-alias-list/): 检索索引别名信息，返回别名与索引的映射关系及别名配置。 API # GET /_aliases GET /{index}/_alias GET /{index}/_alias/{name} HEAD /_aliases HEAD /{index}/_alias HEAD /{index}/_alias/{name} GET /_alias/{name} HEAD /_alias/{name} … - [解析异常 (parsing_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/parsing_exception/): 为什么这个错误发生 # parsing_exception 表示在解析请求内容时发生错误。这个异常包含错误位置信息（行号和列号），帮助定位问题所在。 这个错误可能由以下原因引起： JSON 语法错误：请求体不是有效的 JSON 格式 查询 DSL 语法错误：查询语句语法不正确 字段名错误：引用了不存在的字段 类型不匹配：字段值与映射类型不匹配 缺少必需参数：缺少必需的请求参数 参数格式错误：参 … - [读取搜索请求时出现未预期的 token - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-read-search-request-unexpected-token-token-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.x-8.x 1. 问题含义 # could not read search request. unexpected token [token] 表示 Elasticsearch 在解析搜索请求时，遇到了当前分支不接受的 JSON token，例如 START_ARRAY、VALUE_NUMBER、VALUE_NULL 等。 它通常是更泛化的一类结构错误：当前字段既不是允许的对 … - [资源不存在 (resource_not_found_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/resource_not_found_exception/): 为什么这个错误发生 # resource_not_found_exception 是一个通用的资源未找到异常，表示请求的资源（索引、文档、快照、模板等）不存在。 这个错误可能由以下原因引起： 索引不存在：请求的索引未创建或已被删除 文档不存在：指定的文档 ID 不存在 快照不存在：请求的快照不存在或已被删除 模板不存在：索引模板或组件模板不存在 别名不存在：引用的别名不存在 管道不存 … - [集群发现配置: seed_resolver.timeout](https://easysearch.cn/knowledge-base/easysearch_config/discovery.seed_resolver.timeout/): discovery.seed_resolver.timeout 配置项控制集群发现相关行为。 配置格式 # # 默认配置 discovery.seed_resolver.timeout: default - [非法的导出器资源状态 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/illegal-exporter-resource-status-state-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.11-7.17 1. 错误异常的基本描述 # 非法的导出器资源状态 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [already parsed expand_wildcards - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/already-parsed-expand-wildcards-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.1-8.9 1. 错误异常的基本描述 # already parsed expand_wildcards 是 Elasticsearch 在解析 REST 请求参数时抛出的 ElasticsearchParseException。该异常表示在解析 IndicesOptions 的过程中，expand_wildcards 字段被重复解析， … - [Create api key - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/create-api-key-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # Create api key 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Max children 仅在 v6.5.0 或更高版本支持 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/max-children-is-only-supported-on-v6.5.0-or-higher-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.16-7.17 1. 错误异常的基本描述 # Max children 仅在 v6.5.0 或更高版本支持 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [minute 配置既不是单值也不是数组 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/invalid-time-minute-value-expected-string-number-value-or-an-array-of-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # invalid time minute value. expected string/number value or an array of string/number values; but found [token] 是 Elasticsearch Watcher 功能在解析定时触发器（schedule trigger） … - [Suggester term解析在currentFieldName上失败 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/suggester-term-parsing-failed-on-currentfieldname-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Suggester term解析在currentFieldName上失败 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现 … - [Unsupported url protocol protocol from URL urlToCheck - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unsupported-url-protocol-protocol-from-url-urltocheck-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.16-8.9 1. 错误异常的基本描述 # Unsupported url protocol protocol from URL urlToCheck 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请 … - [保留租约未找到异常 (retention_lease_not_found_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/retention_lease_not_found_exception/): 为什么这个错误发生 # retention_lease_not_found_exception 表示尝试操作一个不存在的保留租约。保留租约用于确保软删除的文档不会被过早清理。 这个错误可能由以下原因引起： 租约已被删除：租约已被删除但操作仍尝试访问 租约 ID 错误：使用了错误的租约 ID 分片恢复后：分片恢复后租约信息丢失 节点重启：节点重启后租约状态未持久化 租约过期： … - [发现Ping超时配置](https://easysearch.cn/knowledge-base/easysearch_config/discovery.zen.ping_timeout/): 配置项作用 # discovery.zen.ping_timeout 配置项用于控制节点在发现集群主节点时的 ping 超时时间。 这是 Easysearch Zen 发现机制中的核心配置，决定了节点等待其他节点响应 ping 请求的最长时间。 配置项属性 # 配置路径: discovery.zen.ping_timeout 数据类型: TimeValue（时间值） 默认值: 3s（3秒） … - [发送失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failure-to-send-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 发送失败 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返回 400、404、409、429、500 … - [启动加密服务失败，无法加载加密密钥 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-start-crypto-service-could-not-load-encryption-key-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # failed to start crypto service, could not load encryption key 表示 Elasticsearch 在启动安全加密服务时，无法从系统密钥材料中派生出可用的加密密钥，导致依赖加密服务的所有功能（如 Watcher 邮件通知凭证加密、安全缓存等）无法正常初始化。 这是一个在节点启动阶 … - [商业友好协议：Easysearch 如何为企业破解开源合规困局](https://easysearch.cn/knowledge-base/insight/business-friendly-licensing-how-easysearch-solves-open-source-compliance-challenges-for-enterprises/): 当一家准备上市的科技公司被投资机构问及核心数据平台的合规风险时，其 CTO 不得不承认：“我们的搜索与分析系统基于 Elasticsearch，这意味着如果未来我们将其作为 SaaS 服务对外提供，可能会触发 SSPL 协议条款，面临被迫开源核心代码的风险。” 在基础软件选型中，开源协议常被误解为“完全免费自由”，实则暗藏商业合规陷阱。Elasticsearch 从 Apache 2.0 … - [固定查询规则操作必须包含 ids 或 docs - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/pinned-query-rule-actions-must-contain-either-ids-or-docs-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.9-8.9 1. 错误异常的基本描述 # 固定查询规则操作必须包含 ids 或 docs 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [必须包含query子句的span查询 – 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/must-have-query-span-query-clause-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.15-8.9 1. 错误异常的基本描述 # 必须包含query子句的span查询 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [搜索线程池配置](https://easysearch.cn/knowledge-base/easysearch_config/thread_pool.search/): 配置项作用 # thread_pool.search 相关配置项控制用于处理搜索和聚合请求的线程池大小和队列行为。搜索线程池直接影响集群的搜索并发能力和响应性能。 配置项类型 # 该配置项为静态配置，需要在启动时设置，修改后需要重启节点才能生效。 配置项列表 # 配置项 默认值 说明 thread_pool.search.size CPU … - [文档不存在 (document_missing_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/document_missing_exception/): 为什么这个错误发生 # document_missing_exception 表示尝试更新或删除一个不存在的文档。当操作的文档 ID 在索引中找不到时，就会抛出此异常。 这个错误可能由以下原因引起： 文档 ID 不存在：提供的文档 ID 在索引中不存在 索引不匹配：文档在另一个索引中，而非当前索引 文档已被删除：文档在操作前被其他进程删除 ID 类型错误：文档 ID 的类型（如字符串 vs 数 … - [无效URI - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/invalid-uri-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.2-8.9 1. 错误异常的基本描述 # 无效URI 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返回 400、404、409、429、500 … - [无效查询：期望但未找到 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/invalid-query-given-expected-but-found-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.14 1. 错误异常的基本描述 # 无效查询：期望但未找到 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法发送重放操作 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-send-replay-operations-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.9-8.9 1. 错误异常的基本描述 # 无法发送重放操作 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法检查请求的白名单 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unable-to-check-request-for-white-listing-how-to-solve-this-elasticsearch-exception/): 适用版本： 7-7.15 1. 错误异常的基本描述 # 无法检查请求的白名单 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法解析季节性类型，可接受的值为 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-seasonality-type-accepted-values-are-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.17 1. 错误异常的基本描述 # 无法解析季节性类型，可接受的值为 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法解析指定监视器状态，期望字段保存日期值（Could not parse watch status for [watchId]. expecting field to hold a date value）- 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-watch-status-for-expecting-field-to-hold-a-date-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.x 1. 错误异常的基本描述 # could not parse watch status for [watchId]. expecting field [...] to hold a date value; found [...] instead 表示某个具体 watch 的状态字段中，本应是日期值的位置出现了错误类型。 与不带 watchId 的版本相比，这条异常的 … - [无法解析索引 indexName 的分片路径和分片 ID shardId - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unable-to-resolve-shard-path-for-index-indexname-and-shard-id-shardid-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.5 1. 错误异常的基本描述 # 无法解析索引 indexName 的分片路径和分片 ID shardId 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常 … - [映射类型名称不应包含'#'字符——如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/mapping-type-name-type-should-not-include-in-it-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # 映射类型名称不应包含'#'字符— 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [期望 START_OBJECT 标记但实际不是 —— 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/expected-start-object-as-the-token-but-was-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.1-8.9 1. 错误异常的基本描述 # 期望 START_OBJECT 标记但实际不是 — 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [未指定半径 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/radius-is-not-specified-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.2-8.9 1. 错误异常的基本描述 # 未指定半径 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [构建存储统计信息时的IO异常 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/io-exception-while-building-store-stats-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 构建存储统计信息时的IO异常 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [查询存储脚本](https://easysearch.cn/knowledge-base/easysearch_api/get-stored-script/): 获取集群中指定存储脚本的信息。 API 格式 # GET /_scripts/{id} API 作用 # 该 API 用于检索集群中的存储脚本： 获取指定 ID 的存储脚本 查看脚本语言和源代码 检查脚本是否存在于集群中 API 参数 # 路径参数 # 参数 类型 是否必填 默认值 描述 {id} String 是 - 要查询的存储脚本 ID 查询参数 # … - [查询数据流统计信息](https://easysearch.cn/knowledge-base/easysearch_api/get-data-stream-stats/): 此 API 用于获取 Easysearch 集群中数据流（Data Stream）的统计信息，包括数据流数量、后备索引数量、存储大小等关键指标。 API # GET /_data_stream/_stats GET /_data_stream/{name}/_stats API 的作用 # 获取数据流的统计信息，用于监控和管理数据流的使用情况。返回的信息包括： … - [查询结果窗口大小配置](https://easysearch.cn/knowledge-base/easysearch_config/config_index.max_result_window/): 配置项作用 # index.max_result_window 配置项控制索引查询中 from + size 的最大值。此配置限制分页查询的结果窗口大小，防止过大的分页请求导致内存溢出。 配置项类型 # 该配置项为动态配置，可以在运行时通过索引设置 API 进行修改。 默认值 # 10000 是否必需 # 可选配置项（有默认值） 取值范围 # 1 ~ 正整数 配置格式 # # … - [正则表达式查询 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/regexp-query-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.3-8.9 1. 错误异常的基本描述 # 正则表达式查询 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [索引选项需要配置字段类型 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/index-options-requires-field-type-to-be-configured-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # 索引选项需要配置字段类型 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [脚本允许类型配置](https://easysearch.cn/knowledge-base/easysearch_config/script.allowed_types/): 配置项作用 # script.allowed_types 配置项控制允许执行的脚本类型（内联脚本或存储脚本）。 是否可选 # 是 默认值 # [] (空列表，允许所有类型) 配置项类型 # 动态配置 - 可以在运行时修改 配置格式 # # 允许所有类型（默认） script.allowed_types: [] # 只允许存储脚本 script.allowed_types: - … - [解析坐标发现 Z 值异常 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/exception-parsing-coordinates-found-z-value-but-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.1 1. 错误异常的基本描述 # 解析坐标发现 Z 值异常 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [解析通配符字段模糊字符串 searchTerm 时出错 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/error-parsing-wildcard-field-fuzzy-string-searchterm-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.9-8.9 1. 错误异常的基本描述 # 解析通配符字段模糊字符串 searchTerm 时出错 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可 … - [远程集群连接数配置](https://easysearch.cn/knowledge-base/easysearch_config/cluster.remote.connections_per_cluster/): 配置项作用 # cluster.remote.connections_per_cluster 配置项用于控制本地集群到每个远程集群建立的最大连接数。 当连接到远程集群时，系统会从种子节点开始发现更多节点，直到达到此配置设置的最大连接数。 配置项属性 # 配置路径: cluster.remote.connections_per_cluster 数据类型: integer 默认值: 3 最小值: … - [重新平衡允许策略配置](https://easysearch.cn/knowledge-base/easysearch_config/cluster.routing.allocation.allow_rebalance/): 配置项作用 # cluster.routing.allocation.allow_rebalance 配置项控制允许执行分片重新平衡的条件。此配置决定了在什么集群状态下，分片可以自动在节点间迁移以实现负载均衡。 配置项类型 # 该配置项为动态配置，可以在运行时通过集群设置 API 进行修改。 默认值 # indices_all_active 是否必需 # 可选配置项（有默认值） 可选值 # … - [analyzer [X] not found for field [name] – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/analyzer-propnode-tostring-not-found-for-field-name-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.17 1. 错误说明 # analyzer [X] not found for field [name] 是 Elasticsearch 在解析字段映射（mapping）时抛出的 MapperParsingException 异常。当 Elasticsearch 在索引的 mapping 定义中为一个字段指定了某个分析器（analyzer），但在当前索引的分析器注册表中 … - [Completion字段类型必须被索引 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/completion-field-type-must-be-indexed-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.9-7.9 1. 错误异常的基本描述 # Completion字段类型必须被索引 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [ConcreteSetting getKey 格式错误的值——如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/concretesetting-getkey-is-malformed-value-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # ConcreteSetting getKey 格式错误的值— 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Explain TYPE should be specified at most once - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/explain-type-should-be-specified-at-most-once-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Explain TYPE should be specified at most once 是 Elasticsearch SQL 模块在解析 EXPLAIN 语句时抛出的语法错误。当一条 EXPLAIN 语句中出现多个 TYPE 子句时，解析器会通过 ctx.TYPE().size() 检查重复次数，若大于 1 … - [HTTP TCP 发送缓冲区大小配置](https://easysearch.cn/knowledge-base/easysearch_config/http.tcp.send_buffer_size/): 配置项作用 # http.tcp.send_buffer_size 配置项用于控制HTTP 服务器 TCP 连接的发送缓冲区大小。 TCP 发送缓冲区是操作系统内核为每个 TCP 连接分配的内存区域，用于临时存储即将发送到网络的数据。缓冲区大小直接影响网络吞吐量和发送性能。 配置项属性 # 配置路径: http.tcp.send_buffer_size 数据类型: … - [IdPair jobId 删除快照失败 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/idpair-jobid-failed-to-delete-snapshot-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.9 1. 错误异常的基本描述 # [jobId] Failed to delete snapshot [snapshotId] 表示 ML retention 已经完成了过期 model snapshot 的筛选，并拿到了待删除项，但在实际执行某个具体快照删除时失败。这里的 idPair 通常携带 jobId 和 snapshotId 两个关键信息，说明失败已经精确定位 … - [Joining查询无法执行时——如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/joining-queries-cannot-be-executed-when-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # Joining查询无法执行时— 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Meta值不能为空（字段名）- 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/meta-values-can-t-be-null-field-name-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.6-8.9 1. 错误异常的基本描述 # Meta值不能为空（字段名） 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [PBKDF2 盐值长度必须至少为 PBKDF2_MIN_SALT_LENGTH_IN_BYTES 字节 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/pbkdf2-salt-must-be-at-least-pbkdf2-min-salt-length-in-bytes-bytes-long-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.7-8.9 1. 错误异常的基本描述 # PBKDF2 盐值长度必须至少为 PBKDF2_MIN_SALT_LENGTH_IN_BYTES 字节 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下 … - [Span or must include clauses – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/span-or-must-include-clauses-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Span or must include clauses 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口 … - [Transport Ping 调度配置](https://easysearch.cn/knowledge-base/easysearch_config/transport.ping_schedule/): 配置项作用 # transport.ping_schedule 配置项用于定义传输层连接的内部 ping 间隔时间。 配置项属性 # 配置路径: transport.ping_schedule 数据类型: TimeValue（时间值） 默认值: -1（禁用） 是否可选: 是 作用域: NodeScope（节点级别） 动态更新: 否（需要重启节点生效） 配置建议 # 默认配置 # … - [Unknown boolean property [fieldName] - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/unknown-boolean-property-fieldname-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # unknown boolean property [fieldName] 表示 Elasticsearch 在解析 Graph API 配置时，遇到了无法识别的布尔类型属性。 从源码可见，这个异常在 Graph 探索请求的解析路径中抛出，当布尔属性名无法匹配 significance 或 return_detailed_info 等已知 … - [watch 的 input 字段必须是字符串时却给了其他类型 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-input-for-watch-failed-to-parse-must-be-a-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误说明 # could not parse [input] for watch [<id>]. failed to parse [<field>]. must be a string value 是 Elasticsearch Watcher 在解析 watch 定义时抛出的异常。该错误表示 Watcher 的 input 配置中某 … - [主节点故障检测重试次数配置](https://easysearch.cn/knowledge-base/easysearch_config/cluster.fault_detection.leader_check.retry_count/): 配置项作用 # cluster.fault_detection.leader_check.retry_count 配置项控制判定主节点故障前允许的连续检查失败次数。从节点向主节点发送健康检查，只有连续失败达到此次数后，才会判定主节点故障并触发重新选举。 配置项类型 # 该配置项为静态配置，需要在启动时设置，修改后需要重启节点才能生效。 默认值 # 3 是否必需 # 可选配置项（有默认值） … - [分片快照失败 (index_shard_snapshot_failed_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/index_shard_snapshot_failed_exception/): 为什么这个错误发生 # index_shard_snapshot_failed_exception 是在尝试创建索引分片快照时发生的错误。这个错误表明快照过程在分片级别失败了，可能的原因包括： 存储访问问题：在列出快照仓库中的 blob 文件时发生 I/O 错误 重复快照名称：尝试创建与现有快照同名的快照 元数据获取失败：无法获取存储文件的元数据信息 写入元数据失败：无法将分片级快照元数据写入 … - [图形定义中的非法属性——如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/illegal-property-in-graph-definition-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 图形定义中的非法属性— 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [字段 multiFieldName 上声明的类型 type 没有处理器 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/no-handler-for-type-type-declared-on-field-multifieldname-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 字段 multiFieldName 上声明的类型 type 没有处理器 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 … - [字段名不能设置 indexOptions = – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/the-field-name-cannot-have-indexoptions-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.9-7.1 1. 错误异常的基本描述 # 字段名不能设置 indexOptions = 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [字段必须是其中之一 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/field-must-be-either-or-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.1 1. 错误异常的基本描述 # 字段必须是其中之一 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [字段掩码 span 查询不支持 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/field-masking-span-query-does-not-support-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.14 1. 错误异常的基本描述 # 字段掩码 span 查询不支持 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [导入规则库（指定ID追加）](https://easysearch.cn/knowledge-base/easysearch_api/import-ruleset-with-id-append/): 向指定的规则库中追加新规则，保留原有规则。 API 格式 # PUT /_match_rules/{repo_id}/_import API 作用 # 该 API 用于向指定的规则库追加新规则： 追加模式：在现有规则后添加新规则 如果规则库不存在，则创建新的规则库 支持批量导入多条规则 自动重新计算规则偏移量 保留现有元数据（名称、描述、标签） API 参数 # 路径参数 # 参 … - [必须是一个数字——如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/must-be-a-number-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.8-8.9 1. 错误异常的基本描述 # 必须是一个数字— 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [提供的授权凭证不支持 run-as - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/the-provided-grant-credentials-do-not-support-run-as-how-to-solve-this-elasticsearch-exception/): 适用版本： 8.4-8.9 1. 错误异常的基本描述 # 提供的授权凭证不支持 run-as 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无效的类型名称 (invalid_type_name_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/invalid_type_name_exception/): 为什么这个错误发生 # invalid_type_name_exception 表示映射中使用了无效的类型名称。 如何修复 # 1. 使用正确的类型 # PUT /<index> { "mappings": { "properties": { "field": { "type": "text" } # … - [无法将字段映射器名称复制到字段 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/cannot-copy-field-mapper-name-to-fields-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.14-7.15 1. 错误异常的基本描述 # 无法将字段映射器名称复制到字段 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法解析显著性启发式算法 - 在脚本启发式中未找到脚本 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-significance-heuristic-no-script-found-in-script-heuristic-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.5 1. 错误异常的基本描述 # 无法解析显著性启发式算法 - 在脚本启发式中未找到脚本 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可 … - [本地状态在集群状态更新发布到其他节点时被更改 – 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/local-state-was-mutated-while-cs-update-was-published-to-other-nodes-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.11 1. 错误异常的基本描述 # 本地状态在集群状态更新发布到其他节点时被更改 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返 … - [清理 S3 仓库时需要密钥选项 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/secret-key-option-is-required-for-cleaning-up-s3-repository-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.4-7.17 1. 错误异常的基本描述 # secret_key option is required for cleaning up S3 repository 表示 Elasticsearch 在执行 S3 仓库 cleanup 前发现缺少 secret_key。这类错误和 access key 缺失类似，都属于 cleanup 所需认证参数不完整，但 secret key … - [滚动升级自动引导配置](https://easysearch.cn/knowledge-base/easysearch_config/discovery.zen.unsafe_rolling_upgrades_enabled/): 配置项作用 # discovery.zen.unsafe_rolling_upgrades_enabled 配置项用于控制在从 Zen1 到 Zen2 的滚动升级过程中，是否自动引导 Zen2 节点形成新的集群配置。 当集群中最后一个 Zen1 节点离开时，如果启用了此功能，系统会自动配置投票（voting configuration）以确保集群继续运行。 配置项属性 # 配置路径: … - [策略不存在 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/policy-does-not-exist-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.16-8.9 1. 错误异常的基本描述 # 策略不存在 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [自动跟随重试轮询间隔配置](https://easysearch.cn/knowledge-base/easysearch_config/plugins.replication.autofollow.retry_poll_interval/): 配置项作用 # plugins.replication.autofollow.retry_poll_interval 配置项用于控制自动跟随任务重试失败索引的轮询间隔时间。 在跨集群复制（CCR）的自动跟随模式下，当复制操作失败时，失败的索引会被记录。此配置决定了系统需要等待多长时间后，才会清除失败记录并重新尝试复制这些索引。 配置项属性 # 配置路径: … - [获取节点信息](https://easysearch.cn/knowledge-base/easysearch_api/get-node-info/): 获取集群中节点的详细信息，包括节点设置、操作系统信息、进程信息、JVM 信息、线程池、插件等。 API # GET /_cluster/nodes/info GET /_nodes GET /_nodes/{nodeId} GET /_nodes/{nodeId}/{metrics} API 的作用 # 该 API 用于获取集群中节点的详细配置和状态信息，可以返回多种类型的节点信息，包括： … - [远程 Reindex 白名单配置](https://easysearch.cn/knowledge-base/easysearch_config/reindex.remote.whitelist/): 配置项作用 # reindex.remote.whitelist 配置项用于控制从远程 Easysearch 集群进行 Reindex 操作时，允许访问的远程主机地址白名单。这是一个重要的安全配置，防止未授权的远程数据访问。 Reindex 操作允许用户将数据从一个索引复制到另一个索引。当源数据位于远程集群时，此配置确保只有预授权的远程主机可以被访问，避免潜在的安全风险（如 SSRF 攻击）。 … - [需要script字段 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/requires-script-field-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 需要script字段 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [预期字段名为 commands 或数组开始 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/expected-either-field-name-commands-or-start-array-got-instead-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 预期字段名为 commands 或数组开始 表示 Elasticsearch 在集群协调、分片路由或存储恢复链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [Azure proxy host is unknown - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/azure-proxy-host-is-unknown-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Azure proxy host is unknown 是 Elasticsearch 在初始化 Azure Blob Storage 仓库（snapshot repository）时抛出的配置异常。当 Elasticsearch 尝试解析 azure.client.<name>.proxy.host 中配置的代理主机名却无 … - [failed to load analyzer for name - 指定名称的分析器加载失败](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-load-analyzer-for-name-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # failed to load analyzer for name 表示 Elasticsearch 已经拿到了分析器名称，但在 AnalysisModule 中无法成功实例化该分析器。源码显示它会先从 analyzers 注册表读取 provider，然后调用 provider.get(environment, key).get() 创 … - [ISM 历史索引保留期配置](https://easysearch.cn/knowledge-base/easysearch_config/index_state_management.history.rollover_retention_period/): 配置项作用 # index_state_management.history.rollover_retention_period 配置项用于控制滚动后的历史索引在被删除前的保留时间。 当历史索引滚动后（创建新索引），旧索引会根据此配置保留一段时间，超过保留期的索引会被自动删除。 配置项属性 # 配置路径: … - [LinearRing 中的点数无效 - 必须大于等于 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/invalid-number-of-points-in-linearring-found-must-be-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # LinearRing 中的点数无效 - 必须大于等于 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可 … - [Nested查询不支持currentFieldName – 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/nested-query-does-not-support-currentfieldname-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # Nested查询不支持currentFieldName 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可 … - [search_after 不能用于 scroll 上下文 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/search-after-cannot-be-used-in-a-scroll-context-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 当搜索请求同时使用 search_after 和 scroll 时，Elasticsearch 会报： `search_after` cannot be used in a scroll context. 这种错误会在请求进入查询上下文时直接被拒绝。 2. 为什么会发生这个错误 # scroll 和 search_after 都是处理 … - [Value must be of type Map parameterName - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/value-must-be-of-type-map-parametername-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.9-8.9 1. 错误异常的基本描述 # Value must be of type Map parameterName 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 … - [Watch HTTP 附件请求返回错误状态码 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/watch-attachment-http-error-status-host-port-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误说明 # Watch[...] attachment[...] HTTP error status host[...]; port[...]; method[...]; path[...]; status[...] 是 Elasticsearch Watcher 在执行 HTTP attachment 动作时抛出的异常。当 Watcher … - [主节点选举初始超时配置](https://easysearch.cn/knowledge-base/easysearch_config/cluster.election.initial_timeout/): 配置项作用 # cluster.election.initial_timeout 配置项控制主节点选举的初始超时时间。这是第一次选举尝试前的随机延迟时间的最大值。选举机制使用随机延迟来避免多个节点同时发起选举导致冲突。 配置项类型 # 该配置项为静态配置，需要在启动时设置，修改后需要重启节点才能生效。 默认值 # 100ms 是否必需 # 可选配置项（有默认值） 取值范围 # 1ms ~ … - [仓库不存在 (repository_missing_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/repository_missing_exception/): 为什么这个错误发生 # repository_missing_exception 表示尝试访问的快照仓库不存在。 这个错误可能由以下原因引起： 仓库名称拼写错误：请求中的仓库名称输入错误 仓库未创建：仓库尚未被创建 仓库被删除：仓库已被删除但客户端仍在引用 大小写不匹配：仓库名称区分大小写 集群重启后丢失：临时配置的仓库在重启后丢失 如何修复这个错误 # 1. 列出所有仓库 # # 查看 … - [允许关闭索引配置](https://easysearch.cn/knowledge-base/easysearch_config/cluster.indices.close.enable/): 配置项作用 # cluster.indices.close.enable 配置项控制是否允许关闭索引（Index Closing）。关闭索引可以释放其占用的资源，但不删除数据。关闭的索引无法进行读写操作，直到重新打开。 配置项类型 # 该配置项为动态配置，可以在运行时通过集群设置 API 进行修改。 默认值 # true（允许关闭索引） 是否必需 # 可选配置项（有默认值） 取值范围 # … - [分片尚未完全恢复 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/shard-didn-t-fully-recover-yet-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # shard didn't fully recover yet 表示某个分片还处在 CREATED 或 RECOVERING 状态时，就被拿去执行快照。源码在真正获取仓库对象和 SnapshotIndexCommit 之前，会先检查 indexShard.state()；如果分片尚未恢复完成， … - [加密 blob 头部长度不足 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/the-encrypted-blob-blobname-is-too-small-bytesread-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.12-8.6 1. 错误异常的基本描述 # The encrypted blob [blobName] is too small [bytesRead] 表示 Elasticsearch 在读取加密仓库（encrypted repository）中的 blob 数据时，发现其大小不足以容纳固定长度的 DEK（Data Encryption Key）ID 头部，因此无法继续解密流 … - [启动数据框 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/starting-dataframe-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.2-7.4 1. 错误异常的基本描述 # 启动数据框 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返回 400、404、409、429、500 … - [处理管道](https://easysearch.cn/knowledge-base/easysearch_api/process-pipeline/): 处理管道（Ingest Pipeline）用于在文档被索引之前对其进行预处理和转换。 API # 创建或更新管道 # PUT /_ingest/pipeline/{id} 获取管道 # GET /_ingest/pipeline GET /_ingest/pipeline/{id} 删除管道 # DELETE /_ingest/pipeline/{id} 模拟管道 # POST … - [数据流](https://easysearch.cn/knowledge-base/easysearch_api/data-stream/): 数据流是一种用于时间序列数据的索引管理机制，自动处理索引的创建和滚动。 API # 创建数据流 # PUT /_data_stream/{name} 获取数据流 # GET /_data_stream GET /_data_stream/{name} 删除数据流 # DELETE /_data_stream/{name} 获取数据流统计 # GET … - [无效 URL - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/invalid-url-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.2-8.9 1. 错误异常的基本描述 # 无效 URL 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返回 400、404、409、429、500 … - [无法对 AggregateDoubleMetricFieldMapper CONTENT TYPE 进行舍入 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/can-t-round-an-aggregatedoublemetricfieldmapper-content-type-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.11-8.9 1. 错误异常的基本描述 # 无法对 AggregateDoubleMetricFieldMapper CONTENT TYPE 进行舍入 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、 … - [无法执行快照生命周期保留策略 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-execute-snapshot-lifecycle-retention-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.5-8.9 1. 错误异常的基本描述 # failed to execute snapshot lifecycle retention 表示你手动触发 SLM 快照保留清理时，retentionService.triggerRetention() 在执行入口阶段就抛出了异常，因此 Elasticsearch 直接返回 ElasticsearchException。根据源码，这个 … - [无法解析主机 Arrays.toString(bindHosts) - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-resolve-host-arrays-tostring-bindhosts-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 无法解析主机 Arrays.toString(bindHosts) 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [无法解析内部查询 (Could not parse inner query) - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-inner-query-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 无法解析内部查询 (Could not parse inner query) 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常 … - [无法解析模型的设置 (Could not parse settings for model model) - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/could-not-parse-settings-for-model-model-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.17 1. 错误异常的基本描述 # 无法解析模型的设置 (Could not parse settings for model model) 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求 … - [未找到 ElasticsearchException – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/no-elasticsearchexception-found-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 未找到 ElasticsearchException 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能 … - [查询字符串前导通配符允许配置](https://easysearch.cn/knowledge-base/easysearch_config/indices.query.query_string.allowleadingwildcard/): 配置项作用 # indices.query.query_string.allowLeadingWildcard 配置项用于控制查询字符串解析器是否允许使用通配符（* 或 ?）作为查询词的开头。 前导通配符查询（如 *search 或 ?query）会导致全索引扫描，严重影响性能。此配置可以禁用此类查询以保护系统。 配置项属性 # 配置路径: … - [查询测试失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-test-query-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.4-7.13 1. 错误异常的基本描述 # 查询测试失败 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [检测到损坏的仓库索引 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/detected-a-corrupted-repository-index-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.13 1. 错误异常的基本描述 # Detected a corrupted repository 表示 Elasticsearch 在解析仓库索引元数据时，发现 repository 内部引用关系已经不一致。当前源码片段给出的典型例子是：某个被快照记录的 index 引用了一个 snapshot UUID，但这个 UUID 并不存在于仓库快照列表中，于是系统认定仓库索 … - [绑定失败 - 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-bind-to-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.16-8.9 1. 错误异常的基本描述 # 绑定失败 表示 Elasticsearch 在网络连接或节点通信链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返回 400、404、409、429、500 … - [解析几何图形错误 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/error-parsing-geometry-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.9-8.9 1. 错误异常的基本描述 # 解析几何图形错误 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [超时 - 如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/time-exceeded-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # 超时 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # 接口可能返回 400、404、409、429、500 … - [跨集群复制跟随者轮询间隔配置](https://easysearch.cn/knowledge-base/easysearch_config/plugins.replication.follower.poll_interval/): 配置项作用 # plugins.replication.follower.poll_interval 配置项用于控制跟随者轮询领导者以获取更改的频率。 配置项属性 # 配置路径: plugins.replication.follower.poll_interval 数据类型: TimeValue（时间值） 默认值: 50ms（50毫秒） 是否可选: 是 作用域: NodeScope（节点级 … - [遇到多个地理位置点值 – 如何解决此 Elasticsearch 异常](https://easysearch.cn/knowledge-base/elasticsearch_error/encountered-more-than-one-geo-point-value-for-a-how-to-solve-this-elasticsearch-exception/): 适用版本： 7.11-7.15 1. 错误异常的基本描述 # 遇到多个地理位置点值 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [配置了多个相同类型的导出器——如何解决此Elasticsearch异常](https://easysearch.cn/knowledge-base/elasticsearch_error/multiple-type-exporters-are-configured-there-can-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-7.15 1. 错误异常的基本描述 # 配置了多个相同类型的导出器— 表示 Elasticsearch 在查询解析、执行或结果归并链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义，还需要结合日志、请求上下文与索引状态一起判断。 常见现象 # … - [集群发现配置: request_peers_timeout](https://easysearch.cn/knowledge-base/easysearch_config/discovery.request_peers_timeout/): discovery.request_peers_timeout 配置项控制集群发现相关行为。 配置格式 # # 默认配置 discovery.request_peers_timeout: default - [非主节点异常 (not_master_exception) 错误排查与解决](https://easysearch.cn/knowledge-base/easysearch_error/not_master_exception/): 为什么这个错误发生 # not_master_exception 表示请求被发送到一个不是主节点的节点，但该操作需要主节点来处理。这通常发生在集群主节点变更期间。 这个错误可能由以下原因引起： 主节点故障：原主节点宕机或故障 主节点选举：集群正在进行主节点选举 节点角色错误：请求发送到了非主节点 网络分区：网络问题导致节点与主节点失联 主节点变更：主节点刚刚发生变更，集群状态尚未同步 候选主节 … - [](https://easysearch.cn/knowledge-base/elasticsearch_error/already-exists-as-alias-how-to-solve-this-elasticsearch-exception/): 适用版本： 6.8-8.9 1. 错误异常的基本描述 # already-exists-as-alias-how-to-solve-this-elasticsearch-exception 表示 Elasticsearch 在认证、授权或安全配置链路中触发了对应异常。结合当前页面已有信息来看，这类问题往往会直接影响请求可用性、数据写入质量、查询结果正确性或集群稳定性，因此不能只看报错字面含义， … - [](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-int-setting-setting-with-value-svalue-how-to-solve-this-elasticsearch-exception/): title: “无法解析整数设置 setting 与值 sValue - 如何解决此 Elasticsearch 异常” date: “2026-02-28T08:00:00+08:00” blogAuthor: “INFINI Labs” category: … - [](https://easysearch.cn/knowledge-base/elasticsearch_error/failed-to-parse-setting-with-value-how-to-solve-this-elasticsearch-exception/): title: “解析设置值失败 - 如何解决此 Elasticsearch 异常” date: “2026-02-03T08:00:00+08:00” blogAuthor: “INFINI Labs” category: “elasticsearch_errors” blogAuthorDesc: … - [2023 年中国数据库年度行业分析报告](https://easysearch.cn/whitepaper/2023-china-db-report/): 本报告由墨天轮数据社区联合众多单位共同编制发布，参与单位如下（排名不分先后）：北京大学、清华大学、达梦数据库、华为技术有限公司、极限科技（INFINI Labs）、深算院 YashanDB、云和恩墨、浪潮 KaiwuDB、百度云、飞轮科技等。 前言 # 本年度报告旨在全面梳理 2023 年中国数据库行业的年度发展情况，从数据库流行度、市场动态、生态建设、资本投资，以及国产数据库在金融行业核心系统 … - [2024 TDBC - 分布式搜索引擎白皮书](https://easysearch.cn/whitepaper/2024-tdbc-search-db-whitepaper/): 本报告的撰写得到了数据库领域多家企业与专家的支持和帮助，主要参与编写单位如下（排名不分先后）： 大数据技术标准推进委员会、极限数据（北京）科技有限公司、拓尔思信息技术股份有限公司、中移（苏州）软件技术有限公司、星环信息科技（上海）股份有限公司、北京人大金仓信息技术股份有限公司、达梦数据技术（江苏）有限公司、腾讯云计算（北京）有限责任公司、中移（杭州）信息技术有限公司。 本报告来源于：CCSA … - [APM 应用可观测性解决方案](https://easysearch.cn/solution/apm-observability/): - [Confluence Wiki 全文搜索解决方案](https://easysearch.cn/solution/confluence-wiki-search/): - [Easysearch v1.0 搜索型数据库基础能力检验报告](https://easysearch.cn/whitepaper/easysearch-search-db-testing-report/): 2023 年 4 月 18 日，在中国信通院组织的第一批“搜索型数据库”产品能力评测中，极限数据 (北京) 科技有限公司（以下简称：极限科技）的 Easysearch 搜索型数据库软件顺利完成了首个搜索型数据库产品能力测试。 该测评依据《搜索型数据库技术要求》进行，该标准融合了国内行业专家丰富的实践经验与智慧，是对搜索型数据库基础能力的综合评判，覆盖数据库基本能力、数据库管理能力、数据库安全能 … - [Easysearch 授权协议](https://easysearch.cn/agreement/easysearch/): Easysearch 授权协议 # 更新日期：2023 年 6 月 8 日 生效日期：2023 年 6 月 8 日 本授权协议（以下简称“协议”）是由您（以下简称“用户”）与极限数据（北京）科技有限公司（以下简称“公司”）之间就公司的软件产品 Easysearch（以下简称“软件”）的使用而订立的法律协议。在同意本协议之前，请仔细阅读并确保您充分理解本协议的所有条款。通过安装、复制或以其他方式使 … - [Easysearch：助力中国一汽降本增效](https://easysearch.cn/case/indexs/using-easysearch-to-help-automotive-companies-reduce-costs/): 客户介绍 # 中国一汽（中国第一汽车集团有限公司，简称“一汽集团”）是中国历史最悠久、规模最大的汽车制造企业之一，成立于 1953 年，总部位于吉林省长春市。作为中国汽车工业的摇篮，一汽集团是中央直属的国有特大型汽车企业，位列世界 500 强，业务涵盖整车研发、生产、销售、出行服务、金融等多个领域。 客户痛点/挑战 # 一汽集团需要针对当前 Elasticsearch(简称：ES) 集群进行优 … - [Elasticsearch VS Easysearch 性能测试报告](https://easysearch.cn/whitepaper/es710-vs-easysearch-performance-test-report/): 概要 # 软件版本： Easysearch v1.19.0 Elasticsearch v7.10.2 本报告通过对不同场景的压测结果进行对比分析，得出以下结论： Easysearch 相比 Elasticsearch 的索引性能显著提升 Easysearch 集群的吞吐性能提升了 40% - 70%，且随着分片数量的增加，性能提升效果更为显著。 Easysearch … - [INFINI Console：助力 Elasticsearch 集群平滑升级，保障业务零中断](https://easysearch.cn/case/indexs/facilitating-smooth-elasticsearch-cluster-upgrades-with-infini-console/): 客户介绍 # 中国人民保险集团股份有限公司（PICC，简称“中国人保”）是中国历史最悠久、规模最大的综合性保险金融集团之一，成立于 1949 年，与新中国同龄。作为国有骨干金融企业，中国人保位列《财富》世界 500 强，2023 年排名第 110 位，业务涵盖保险、投资、科技三大板块，旗下拥有人保财险、人保寿险、人保健康等核心子公司。 客户背景 # … - [INFINI Easysearch 国产替代方案 v1.0](https://easysearch.cn/whitepaper/easysearch-alternative-solution/): 摘要 # 极限科技推出的 Easysearch 是一款国产化、AI 原生、高性能的分布式搜索引擎，旨在替代 Elasticsearch 在企业搜索与分析场景中的应用。其具备 自主可控、向量检索、存储压缩、企业级安全与运维能力，并已在一汽、PICC、移动云等大型企业中成功落地，实现了性能提升、成本降低、平滑迁移的显著效果。配套的 INFINI Cloud 与 Coco AI 进一步构建了从基础设施 … - [INFINI Easysearch 搜索引擎软件产品技术白皮书](https://easysearch.cn/whitepaper/easysearch-whitepaper/): 摘要 # 长期以来，我国信息技术基础软件长期受制于人，数据库作为信创核心环节，搜索引擎数据库领域的国产替代需求日益迫切。全球搜索引擎数据库市场由 Elasticsearch 主导，中国产品占比较低。随着政策支持与行业关注度提升，国产分布式搜索引擎迎来重大发展机遇。 分布式搜索引擎在金融、通信、制造、零售、医疗、教育等行业的海量数据检索与分析场景中发挥着不可或缺的作用。 INFINI … - [Oceanbase 高级全文搜索方案](https://easysearch.cn/solution/oceanbase-advanced-search/): - [PB 级大规模日志分析解决方案](https://easysearch.cn/solution/pb-log-analytics/): - [个性化推荐](https://easysearch.cn/features/personalized-recommendation/): - [互联网高性能敏感词检测方案](https://easysearch.cn/solution/internet-sensitive-word-detection/): - [交通卡口大数据搜索平台解决方案](https://easysearch.cn/solution/traffic-checkpoint-big-data-search/): - [作业帮跨云集群的就近本地访问](https://easysearch.cn/case/indexs/how-to-build-cross-cloud-cluster-with-local-access/): 客户介绍 # 作业帮是中国领先的在线教育平台，成立于 2014 年。作业帮将人工智能、大数据等技术与教育教学深度融合，打造覆盖教、学、考、评、管、研等全场景智慧教育解决方案，满足用户对高效、便捷学习体验的需求。 业务需求 # 作业帮为了确保某个业务 Elasticsearch 集群的高可用，在百度云和华为云上面采取了双云部署，即将单个 Elasticsearch 集群跨云进行部署，并且要求业务 … - [保险行业保单检索解决方案](https://easysearch.cn/solution/insurance-policy-retrieval/): - [全文检索](https://easysearch.cn/features/full-text-search/): - [公安系统大数据检索解决方案](https://easysearch.cn/solution/public-security-system/): - [分布式架构](https://easysearch.cn/features/distributed-architecture/): - [向量搜索](https://easysearch.cn/features/vector-search/): - [国密与国产化](https://easysearch.cn/features/national-encryption/): - [地理空间位置检索](https://easysearch.cn/features/geo-search/): - [多模态搜索](https://easysearch.cn/features/multimodal-search/): - [安全登录](https://easysearch.cn/features/secure-login/): - [异步搜索](https://easysearch.cn/features/async-search/): - [快照搜索](https://easysearch.cn/features/snapshot-search/): - [抖音短视频搜索解决方案](https://easysearch.cn/solution/short-video-search/): - [授权协议](https://easysearch.cn/agreement/console/): 授权协议 # 更新日期：2023 年 6 月 8 日 生效日期：2023 年 6 月 8 日 本授权协议（以下简称“协议”）是由您（以下简称“用户”）与极限数据（北京）科技有限公司（以下简称“公司”）之间就公司的软件产品（以下简称“软件”）的使用而订立的法律协议。在同意本协议之前，请仔细阅读并确保您充分理解本协议的所有条款。通过安装、复制或以其他方式使用本软件，您即表示您接受本协议的所有条款和条 … - [插件管理](https://easysearch.cn/features/plugin-management/): - [数据加密与脱敏](https://easysearch.cn/features/data-encryption/): - [数据库非结构化全文搜索方案](https://easysearch.cn/solution/database-unstructured-search/): - [极限网关助力好未来 Elasticsearch 容器化升级](https://easysearch.cn/case/indexs/using-gateway-help-tal-es-k8s-upgrade/): 客户介绍 # 好未来（NYSE：TAL）是一家以内容能力与科技能力为基础，以科教、科创、科普为战略方向，助力人的终身成长，并持续探索创新的科技公司。 好未来的前身学而思成立于 2003 年，2010 年在美国纽交所正式挂牌交易。好未来以“爱与科技助力终身成长”为使命，致力成为持续创新的组织。 客户痛点/挑战 # 好未来的日志 Elasticsearch（简称：ES）拥有数十套服务集群，几百台物 … - [极限网关助力移动云盘大幅降低搜索查询和写入延迟](https://easysearch.cn/case/indexs/use-gateway-helps-caiyun-reduce-es-search-query-and-write-latency/): 客户介绍 # 中国移动云盘（原“和彩云网盘”）为用户提供微信文件、手机图片、通讯录等数字资产的存储备份、在线管理、群组共享等服务；支持任一终端上传，所有终端 (APP、小程序、iPad 、PC、TV、网页端等) 同步可见，月活跃用户规模位居行业第二，致力于成为 5G 时代用户个人与家庭的数字资产管理中心。 客户痛点/挑战 # 随着移动云盘业务的快速增长，移动云盘平台的搜索数据库资产已达 70+ … - [极限网关实现 Elasticsearch 异地容灾](https://easysearch.cn/case/indexs/elasticsearch-remote-disaster-recovery/): 客户介绍 # 该客户为国内知名的科创服务大数据平台，为用户和企业提供知识产权、资源搜索、匹配、管理等服务，致力打造国际一流的科创服务大数据基础设施。 客户痛点/挑战 # 随着业务规模的增长，业务侧对使用的 Elasticsearch（简称：ES）集群的数据可靠性、集群稳定性等方面的要求越来越高。需要建设一个双机房的高可用业务架构，实现 Elasticsearch 异地容灾，当一端机房出现不可用 … - [某保险集团业务的索引速度百倍提升之旅](https://easysearch.cn/case/indexs/200x-indexing-speedup/): 业务挑战 # 某大型保险集团的保单查询业务，通过将数据库的常用字段放到 Elasticsearch 里面，用来提升查询性能，集群部署在 14 台物理机上面，每个物理机上面部署了 4 个 Elasticsearch 实例， 整个集群约有 90 多亿条数据，索引主分片存储接近 5 TB，每天的增量更新数据大概在 6 亿条左右，由于业务上的特殊性，全国的所有的业务数据都存放在一个索引里面， 造成了单个 … - [某医药电子商务平台 ES 集群无缝跨云迁移](https://easysearch.cn/case/indexs/es-cross-cloud-migration-in-pharmaceutical-e-commerce-industry/): 客户介绍 # 该客户是中国医药电子商务领域的佼佼者，其核心使命是为广大医药企业以及医疗机构提供全方位、高效便捷的在线服务。通过其精心打造的全程网上药品交易服务平台，该客户不仅提供了信息服务和技术支持，还实现了信息流、物流、资金流的高度协同，从而打造了一个高效运转的互联网药品批发交易市场。 客户痛点/挑战 # 客户在腾讯云上部署了若干个 Elasticsearch（简称：ES）集群，基于公司业务 … - [某货运平台从自建 ES 集群平滑迁移至阿里云](https://easysearch.cn/case/indexs/smoothly-migrated-the-self-built-es-cluster-to-aliyun/): 客户介绍 # 该客户作为国内领先的数字货运平台，深度融合云计算、大数据、移动互联网和人工智能技术，为公路运输物流行业提供高效便捷的管车配货工具。它全面覆盖车找货、货找车的信息及交易服务，推动交通运输降本增效，实现数字经济对实体经济的深度赋能，助力行业数字化转型。 客户痛点/挑战 # 客户有几十个自建 Elasticsearch（简称：ES）集群，用于支撑内部用户、货源、交易、营销、日志等相关核 … - [欢迎加入合作伙伴](https://easysearch.cn/partner/apply/): - [气象行业大规模元数据检索解决方案](https://easysearch.cn/solution/meteorological-big-data/): - [海关出入境系统实时检索解决方案](https://easysearch.cn/solution/customs-entry-exit-retrieval/): - [涉黄涉恐舆情监测解决方案](https://easysearch.cn/solution/public-opinion-monitoring/): - [电商系统商品搜索与推荐解决方案](https://easysearch.cn/solution/ecommerce-search-recommendation/): - [石油行业大数据检索解决方案](https://easysearch.cn/solution/petroleum/): - [移动云携手极限科技，实现 Elasticsearch 国产化替代与云原生升级](https://easysearch.cn/case/indexs/ecloud-localization-elasticsearch/): 客户介绍 # 移动云隶属于中国移动通信集团公司，是建立在中国移动“大云”的基础上，自主技术研发而成的公有云平台，通过服务器虚拟化、对象存储、网络安全能力自动化、资源动态调度等技术，将计算、存储、网络、安全、大数据、开放云市场等作为服务提供，客户根据其应用的需要可以按需使用、按使用付费。 需求背景 # 移动云作为国内领先的云计算服务提供商，一直致力于提升其在搜索领域的服务能力。随着业务的快速发 … - [第三方集成](https://easysearch.cn/features/third-party-integration/): - [管理用户和角色](https://easysearch.cn/features/user-role-management/): - [细粒度权限治理](https://easysearch.cn/features/granular-permission/): - [联系我们](https://easysearch.cn/company/contact/): - [聚合引擎](https://easysearch.cn/features/aggregation-engine/): - [航空客票系统大数据检索解决方案](https://easysearch.cn/solution/airline-ticketing/): - [航运航空大数据检索解决方案](https://easysearch.cn/solution/aviation-shipping/): - [规则引擎](https://easysearch.cn/features/rule-engine/): - [语义搜索](https://easysearch.cn/features/semantic-search/): - [跨集群复制](https://easysearch.cn/features/cross-cluster-replication/): - [跨集群搜索](https://easysearch.cn/features/cross-cluster-search/): - [达梦数据库全文搜索解决方案](https://easysearch.cn/solution/dameng-database-search/): - [金融系统风险控制规则引擎方案](https://easysearch.cn/solution/financial-risk-control-rule-engine/): - [铁路档案管理系统搜索解决方案](https://easysearch.cn/solution/railway-archives/): - [铁路系统大数据检索解决方案](https://easysearch.cn/solution/railway-big-data/): ## Other Resources - [Sitemap](https://easysearch.cn/sitemap.xml): Full machine-readable sitemap. - [RSS Feed](https://easysearch.cn/index.xml): Latest updates and posts.