适用版本： 6.8-8.9
1. 错误异常的基本描述 #
Missing field name in graph vertices definition 是 Elasticsearch Graph API 在解析 vertices 定义时抛出的 parse_exception 类型异常。该错误表示 Graph Explore 请求中某个 vertices 对象缺少必需的 field 属性，导致 Elasticsearch 无法识别要基于哪个字段构建图顶点。
常见现象 #
- 调用 Graph Explore API（
_graph/explore）时直接返回400 Bad Request，响应体中包含Missing field name in graph vertices definition错误信息。 - Kibana Graph 插件或自定义可视化面板无法正常渲染图谱，前端收到解析失败报错。
- 在 Elasticsearch 服务端日志中可以看到
ElasticsearchParseException或parse_exception相关记录，并指向 Graph 模块的VertexRequest解析逻辑。
典型报错与异常栈 #
{
"error": {
"root_cause": [
{
"type": "parse_exception",
"reason": "Missing field name in graph vertices definition"
}
],
"type": "parse_exception",
"reason": "Missing field name in graph vertices definition"
},
"status": 400
}
服务端日志中对应的源码逻辑大致如下：
if (field == null) {
throw new ElasticsearchParseException(
"Missing field name in graph vertices definition", token.name());
}
VertexRequest vr = currentHop.addVertexRequest(field);
2. 为什么会发生这个错误 #
Graph Explore API 的 vertices 数组中的每个元素都必须指定 field 属性，用于告诉 Elasticsearch 从哪个字段提取词项作为图的顶点。当解析器遍历 vertices 对象后，field 值仍为 null，就会触发此异常。
常见原因通常包括：
- 完全遗漏
field属性：在构造vertices对象时忘记填写field，或者从旧代码/模板复制时遗漏了该字段。 field写错层级：将field错误地嵌套在include、exclude或其他子对象中，而不是作为vertices对象的顶级属性。- 动态生成请求时的条件分支缺陷：使用代码动态构造 Graph 请求时，某些条件分支未正确赋值
field，导致最终生成的 JSON 中缺少该字段。 - 模板变量未替换：在使用 Mustache 或其他模板引擎生成请求体时，
{{field}}等占位符未被正确替换，导致最终请求中field值为空或不存在。 - 多 hop 配置时复制粘贴错误：在配置多个
hop和vertices时，从其他部分复制配置但忘记更新field值。
3. 如何排查和解决这个异常 #
建议按以下步骤定位问题：
- 从完整报错响应中提取出引发异常的请求体，重点关注
vertices数组中的每个对象。 - 检查每个
vertices对象是否都包含顶级field属性，且值不为空字符串。 - 如果请求体是通过代码动态生成的，打印最终序列化的 JSON，确认
field在序列化后确实存在。 - 对照 Elasticsearch 官方文档中 Graph Explore API 的请求格式，验证整体结构是否正确。
- 如果是 Kibana Graph 插件发出的请求，检查其配置面板中是否正确选择了顶点字段。
排查时需要注意的问题 #
field必须是vertices对象的直接属性，不能嵌套在其他子对象中。field的值必须是索引中已存在的字段名，且字段类型应为keyword或经过keyword类型处理的字段，否则即使不报此错，图谱结果也可能不符合预期。- 如果使用了多个
hop，每个hop下的vertices都需要独立检查，不能假设它们会自动继承上一个 hop 的配置。
4. 如何解决这个错误 #
方案一：补齐 field 属性
#
确保每个 vertices 对象都包含 field 属性。以下是一个最小合法示例：
POST /my-index/_graph/explore
{
"vertices": [
{
"field": "user_id.keyword"
}
],
"connections": {
"vertices": [
{
"field": "product_id.keyword"
}
]
}
}
方案二：检查对象层级 #
如果 field 已存在但不是顶级属性，需要将其提升到 vertices 对象的根级别：
// 错误写法：field 被错误嵌套
{
"vertices": [
{
"include": ["abc"],
"settings": {
"field": "user_id.keyword"
}
}
]
}
// 正确写法：field 是 vertices 的顶级属性
{
"vertices": [
{
"field": "user_id.keyword",
"include": ["abc"]
}
]
}
方案三：从最小请求重建 #
如果请求体结构复杂，建议先使用只包含一个 vertices 的最小合法请求验证连通性，再逐步添加 include、exclude、size、min_doc_count 等配置：
POST /my-index/_graph/explore
{
"vertices": [
{
"field": "user_id.keyword",
"size": 10
}
]
}
借助 INFINI 产品提升排障效率 #
- INFINI Console 适合查看索引 mapping、字段列表和集群状态，帮助快速确认目标字段是否存在以及字段类型是否适合作为图顶点。
- INFINI Gateway 可以部署在 Elasticsearch 前面，记录所有 Graph API 请求和响应，便于捕获不完整请求体并定位是哪一层生成的错误请求。
5. 预防建议 #
- 对 Graph 请求体引入 JSON Schema 校验，在发送前确保
vertices数组中每个对象都包含非空field属性。 - 使用结构化对象（如 Java 中的 DTO、Python 中的 dataclass）构建请求，而非手工拼接 JSON 字符串，利用编译期或运行时类型检查减少遗漏。
- 为 Graph Explore DSL 编写回归测试，覆盖单 hop、多 hop、带 include/exclude、带 size 限制等常见场景。
- 在团队内部建立 Graph API 请求模板，新需求基于模板修改，避免从零开始手写请求体。
- 对动态生成请求的代码增加单元测试，断言序列化后的 JSON 中包含必需的
field字段。
6. 小结 #
Missing field name in graph vertices definition 表示 Graph Explore 请求中 vertices 定义缺少必填的 field 属性。修复方向很明确：补上 field，确保其位于 vertices 对象的顶级位置，且值为索引中真实存在的字段名。通过引入请求校验、结构化对象和回归测试，可以有效避免此类问题重复出现。
相关错误 #
- missing-suggestion-object-how-to-solve-this-elasticsearch-exception
- failed-to-parse-term-vectors-request-unknown-field-how-to-solve-this-elasticsearch-exception
- the-required-field-option-fieldname-field-getpreferredname-is-missing-how-to-solve-this-elasticsearch-exception
附：日志上下文 #
throw new ElasticsearchParseException("Unknown numeric property: [" + fieldName + "]");
}
}
}
if (field == null) {
throw new ElasticsearchParseException("Missing field name in graph vertices definition", token.name());
}
VertexRequest vr = currentHop.addVertexRequest(field);
if (includes != null) {
for (TermBoost tb : includes.values()) {
vr.addInclude(tb.getTerm(), tb.getBoost());
