适用版本： 6.8-8.9
1. 错误说明 #
在使用 Elasticsearch 的 _termvectors 接口时，如果请求体中 fields 字段的格式不符合要求，就会触发如下异常：
failed to parse term vectors request. field [fields] must be an array
这是一个解析阶段的异常，Elasticsearch 在反序列化请求体时发现 fields 的值不是 JSON 数组类型，因此直接拒绝请求并返回 400 Bad Request。
常见现象 #
- 调用
_termvectors接口时立即返回400错误，请求未进入执行阶段。 - 返回体中包含
ElasticsearchParseException，并明确指出field [fields] must be an array。 - 使用 SDK（如 Java High Level REST Client、Python elasticsearch-py 等）发送请求时，若构造参数方式不当，也容易稳定复现此错误。
- 如果是通过模板或动态拼接 JSON 的方式生成请求体，往往整个批次的请求都会失败。
2. 原因分析 #
_termvectors 接口用于获取一个或多个字段的词向量（term vectors）信息，fields 参数的作用是指定要分析的字段列表。Elasticsearch 在解析该参数时有明确的格式要求：
fields 必须是一个 JSON 数组，即使只有一个字段也要写成数组形式。
常见错误写法 #
{
"fields": "title"
}
上面这种写法中，"title" 是一个字符串，而不是数组，因此会触发解析异常。
正确写法 #
{
"fields": ["title"]
}
其他常见原因 #
- 单字段未用数组包裹：这是最常见的原因，开发者容易误以为单个字段可以直接写成字符串。
- SDK 序列化问题：某些 SDK 在构造请求时，如果传入的是单个字符串而不是集合类型，序列化后生成的 JSON 就不是数组。
- 模板渲染错误：使用模板引擎动态生成 JSON 时，如果只有一个字段，模板可能将其渲染为字符串而非数组。
- 字段值为空或 null：
fields被设置为null或空字符串，而非空数组[]。
3. 解决方案 #
步骤一：确认当前请求格式 #
先抓取实际发送给 Elasticsearch 的请求体，确认 fields 字段的格式。以 curl 为例：
curl -X POST "localhost:9200/my_index/_termvectors/1" \
-H "Content-Type: application/json" \
-d '{
"fields": "title"
}'
上述请求会触发错误。
步骤二：修正为数组格式 #
将 fields 的值改为数组：
curl -X POST "localhost:9200/my_index/_termvectors/1" \
-H "Content-Type: application/json" \
-d '{
"fields": ["title"]
}'
如果需要多个字段，写法如下：
{
"fields": ["title", "content", "description"]
}
步骤三：在代码中检查参数构造方式 #
以 Python 为例，确保传入的是列表：
from elasticsearch import Elasticsearch
es = Elasticsearch("https://localhost:9200")
response = es.termvectors(
index="my_index",
id="1",
body={
"fields": ["title", "content"]
}
)
print(response)
以 Java 为例：
TermVectorsRequest request = new TermVectorsRequest("my_index", "1");
request.setFields(new String[]{"title", "content"});
步骤四：验证修复效果 #
修复后再次发送请求，应返回正常的词向量结果，包含每个 term 的 term_freq、tokens、offsets 等信息。
4. 预防措施 #
- 在代码中始终使用数组/列表类型构造
fields参数，即使只有一个字段也不要省略数组括号。 - 对请求体做序列化前校验，确保动态生成的 JSON 符合 Elasticsearch 的接口契约。
- 在测试环境覆盖单字段和多字段两种场景，避免模板渲染只测试了多字段情况而遗漏单字段场景。
- 封装统一的请求构造方法，在方法内部强制将
fields参数转为集合类型，避免散落在各处的构造代码各自为战。 - 参考官方文档确认参数格式，不同版本的 Elasticsearch 对
_termvectors接口的参数要求一致，但其他接口的类似参数可能有不同约定。
5. 小结 #
failed to parse term vectors request. field [fields] must be an array 是一个典型的请求格式错误，根因几乎都是 fields 参数未使用数组格式。修复方法简单明确：将 fields 的值改为 JSON 数组即可。建议在代码层面统一规范参数构造方式，从根本上避免此类问题。
相关错误 #
附：日志上下文 #
if (token == XContentParser.Token.START_ARRAY) {
while (parser.nextToken() != XContentParser.Token.END_ARRAY) {
fields.add(parser.text());
}
} else {
throw new ElasticsearchParseException(
"failed to parse term vectors request. field [fields] must be an array"
);
}
