Meilisearch facet-search 报 invalid_facet_search_facet_name

POST /indexes/{uid}/facet-search 做分面值自动补全时，如果 facetName 属性不在索引 filterableAttributes 列表中（拼错、大小写不符或忘声明），返回 HTTP 400，错误码 invalid_facet_search_facet_name；facetName 参数整个缺失则报 missing_facet_search_facet_name。facet search 的前置条件是属性必须可过滤。解法：把属性声明为 filterable 并等任务完成，再核对 facetName 与文档字段完全一致。适用 Meilisearch 全版本。

Issue & Env（案发现场与环境）

业务场景：搜索页面的分面下拉框需要自动补全，调用 POST /indexes/books/facet-search，body 传 {"facetName": "genres", "facetQuery": "fic"}，返回 400。genres 从未加入 filterableAttributes；或把 facetName 拼成了 "genre"（少了复数 s）。
环境：Meilisearch v1.54.3，curl / 任意 SDK 均可复现。
关键区分：这是 facet-search 端点特有的参数校验错误，与主搜索端点的 invalid_search_filter 是两套错误码；facetName 缺失时走的是另一个错误码 missing_facet_search_facet_name。
典型触发：前端分面下拉输入框里用户输入 fic 触发自动补全请求，接口 400 后下拉框没有任何候选；或后端拼请求时 facetName 取值取到了 undefined/拼写错误，同样踩中本文的错误码。

StackTrace（堆栈日志）

官方 Search for facet values API 文档的前置条件原文：

Prerequisite: The facetName attribute must be in the index’s filterableAttributes list. Facet search will not work without this configuration.

错误码参考页对 invalid_facet_search_facet_name 的描述原文：

The attribute used for the facetName field is either not a string or not defined in the filterableAttributes list.

官方规范（specs 0061）中该错误的响应结构（HTTP 400 同步返回，message 为运行期生成）：

{
    "message": "`:deserr_helper`",
    "code": "invalid_facet_search_facet_name",
    "type": "invalid_request",
    "link": "https://docs.meilisearch.com/errors#invalid_facet_search_facet_name"
}

facetName 整个缺失时走 missing_facet_search_facet_name，错误码参考页描述原文：

The facetName parameter is required.

Reproduce（复现代码）

# 1. 索引 books 未声明任何 filterableAttributes（默认空数组）

# 2. 调用 facet-search——报 invalid_facet_search_facet_name
curl -X POST 'http://localhost:7700/indexes/books/facet-search' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer aSampleMasterKey' \
  --data-binary '{"facetName": "genres", "facetQuery": "fic"}'

# 返回 400: {"code": "invalid_facet_search_facet_name", "type": "invalid_request", ...}

# 3. 忘了传 facetName——报 missing_facet_search_facet_name
curl -X POST 'http://localhost:7700/indexes/books/facet-search' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer aSampleMasterKey' \
  --data-binary '{"facetQuery": "fic"}'

# 返回 400: {"code": "missing_facet_search_facet_name", "type": "invalid_request", ...}

Root Cause（根因分析）

facet-search 端点的设计前提：分面值统计依赖与 facets、filter 相同的内部数据结构，只有 filterableAttributes 里的属性才有分面值可供搜索。所以 API 文档把“facetName 必须在 filterableAttributes”列为硬性前置条件（Prerequisite），不满足就直接 400，不会像主搜索的 facets 参数那样静默忽略。

为什么这里报错而不是静默

主搜索端点的 facets 参数对未声明属性是静默忽略（不报错、只是不返回统计），但 facet-search 把 facetName 当作端点的核心输入来做严格校验：属性没有分面值可供搜索，整个端点就没有意义，因此直接 400。排查时不能套用主搜索端点的“静默忽略”经验，两个端点的容错策略完全不同。

常见触发原因

facetName 与文档字段名不完全一致：拼写错误、大小写不符（如 Genres）、丢了嵌套前缀（如写成 language 而字段是 specs.language）。
只声明了搜索/展示用字段，忘了把分面字段加进 filterableAttributes。
设置了 filterableAttributes 但没等异步任务 succeeded 就调用——此时校验仍失败。
facetName 传了非字符串类型（如数字）也会触发 invalid_facet_search_facet_name。

容易混淆的相邻问题

facetQuery 只匹配第一个词：搜 Jane 能命中 Jane Austen，搜 Austen 则匹配不到——这是“能搜但搜不到”，不报错，与本文的 400 无关。
数值型分面值不可被 facet search 搜索，官方原文 “Numeric facet values are not searchable. Convert numbers to strings if you need to search them as facets.”——同样不报错，而是搜不到。

The Fix（解决方案）

第一步：把 facetName 属性加入 filterableAttributes

curl -X PUT 'http://localhost:7700/indexes/books/settings/filterable-attributes' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer aSampleMasterKey' \
  --data-binary '["genres", "rating", "language"]'

第二步：等设置任务完成

轮询 GET /tasks/{taskUid} 直到 status: succeeded。设置更新会触发该索引全量重建，耗时与数据量成正比。

curl -X POST 'http://localhost:7700/indexes/books/facet-search' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer aSampleMasterKey' \
  --data-binary '{"facetName": "genres", "facetQuery": "fic"}'

# 返回: {"facetHits": [{"value": "Fiction", "count": 42}], "facetQuery": "fic", "processingTimeMs": 0}

排查顺序建议

GET /indexes/{uid}/settings/filterable-attributes 核对声明列表里有没有该属性。
核对 facetName 与文档字段完全一致（大小写、嵌套前缀）。
确认 facetName 没有被漏传（漏传报的是 missing_facet_search_facet_name）。
其它参数校验兜底：facetQuery 应为 string 或 null（报 invalid_facet_search_query）；exhaustiveFacetCount 应为 boolean（报 invalid_facet_search_exhaustive_facet_count）。
若确认属性已声明且拼写无误仍报错，用 GET /indexes/{uid}/settings/facet-search 检查 facetSearch 索引设置是否被改成了 false——该设置默认 true，被关闭后调用会报 facet_search_disabled（错误码不同，别混淆）。

References（参考来源）

Search for facet values API — Meilisearch 官方文档meilisearch-docs
Error codes — Meilisearch 官方文档meilisearch-docs
Error Format and Definitions — Meilisearch 规范文档meilisearch-spec