缺少 explanation description - 如何解决此 Elasticsearch 异常

适用版本： 6.8-8.x

1. 错误异常的基本描述 #

missing explanation description 出现在 Elasticsearch 解析 Explanation 结构时。Explanation 通常包含 value、description 和可选的 details；保留代码显示，只要 description 为空，就会直接抛出 ParsingException。

常见现象 #

• 读取 explain 结果、测试数据或某些内部序列化内容时失败。
• 日志里常与 missing explanation value 一起出现，说明 Explanation 对象字段不完整。
• 某些自定义集成或回放测试更容易遇到，因为它们会手工构造 explanation JSON。

2. 为什么会发生这个错误 #

• explanation JSON 中没有 description 字段。
• 上游程序只保留了分值 value，却漏掉描述文本。
• 回放、Mock、测试桩或插件生成的 explanation 结构不完整。
• 反序列化的内容被裁剪，导致必要字段丢失。

3. 排查步骤 #

1. 找到触发异常的 explanation JSON 或响应片段。
2. 检查是否同时包含 value 与 description。
3. 如果 explanation 由自定义程序生成，核对序列化逻辑是否遗漏描述字段。
4. 对比一个正常 explanation 结构，确认 details 是否只是可选字段。
5. 如果问题来自测试数据，优先修复样例而不是修改解析器。

4. 修复建议 #

• 补齐 description 字段，确保它始终为非空字符串。
• 不要手工裁剪 Elasticsearch explain 响应中的必要字段。
• 为 Mock / 测试数据增加 schema 校验，确保 explanation 结构完整。
• 如果中间层会转发或存储 explain 结果，避免只保留数值部分。

5. 小结 #

这个异常很直接：Explanation 对象缺了 description。修复点通常就在生成、存储或回放该 JSON 的那一层，而不是查询逻辑本身。

相关错误 #

• failed-to-parse-request：请求解析失败
• failed-to-parse-object-expected-start-object-but-was：对象解析失败
• field-missing：geo 点字段缺失

附：日志上下文 #

下面保留当前页面中的源码或日志片段，便于继续结合异常调用栈定位问题：

}
if (value == null) {
    throw new ParsingException(parser.getTokenLocation(); "missing explanation value");
}
if (description == null) {
    throw new ParsingException(parser.getTokenLocation(); "missing explanation description");
}
return Explanation.match(value; description; details);
}
private static void buildExplanation(XContentBuilder builder; Explanation explanation) throws IOException {