错误代码
查阅本页面获取使用 Meilisearch API 时可能遇到的所有错误代码列表。
本页面是 Meilisearch API 错误的完整列表。
api_key_already_exists
已存在具有相同 uid 的 API 密钥。
api_key_not_found
无法找到请求的 API 密钥。
bad_request
请求无效，请查看错误信息获取更多详情。
batch_not_found
请求的批次不存在。请确认您使用了正确的 uid。
database_size_limit_reached
请求的数据库已达到最大容量限制。
document_fields_limit_reached
文档超过了每个文档最多 65,535 个字段的限制。
document_not_found
无法获取请求的文档。可能文档不存在，或数据库处于不一致状态。
dump_process_failed
在创建 dump 文件过程中发生错误，任务已中止。
facet_search_disabled
当facetSearch 索引设置为 false 时，查询了 /facet-search 路由。
feature_not_enabled
您尝试使用了未激活的实验性功能。
immutable_api_key_actions
API 密钥的 actions 字段不可修改。
immutable_api_key_created_at
API 密钥的 createdAt 字段不可修改。
immutable_api_key_expires_at
API 密钥的 expiresAt 字段不可修改。
immutable_api_key_indexes
API 密钥的 indexes 字段不可修改。
immutable_api_key_key
API 密钥的 key 字段不可修改。
immutable_api_key_uid
API 密钥的 uid 字段不可修改。
immutable_api_key_updated_at
API 密钥的 updatedAt 字段不可修改。
immutable_index_uid
索引的 uid 字段不可修改。
immutable_index_updated_at
索引的 updatedAt 字段不可修改。
index_already_exists
index_creation_failed
尝试创建索引时发生错误，请参阅我们的 索引创建指南。
index_not_found
未找到具有该 uid 的索引，请参阅我们的 索引创建指南。
index_primary_key_already_exists
请求的索引已存在主键，且 无法更改。
index_primary_key_multiple_candidates_found
主键推断 失败，因为接收到的文档包含多个以 id 结尾的字段。请使用 更新索引端点 手动设置主键。
internal
Meilisearch 遇到内部错误。请检查错误信息，如有需要可 提交问题。
invalid_api_key
请求的资源受 API 密钥保护。提供的 API 密钥无效。更多信息请参阅我们的 安全教程。
invalid_api_key_actions
提供的 API key 资源中的 actions 字段无效。该字段应为表示操作名称的字符串数组。
invalid_api_key_description
提供的 API key 资源中的 description 字段无效。该字段应为字符串或设置为 null。
invalid_api_key_expires_at
提供的 API key 资源中的 expiresAt 字段无效。该字段应为 RFC 3339 格式的未来日期或时间，或设置为 null。
invalid_api_key_indexes
提供的 API key 资源中的 indexes 字段无效。该字段应为表示索引名称的字符串数组。
invalid_api_key_limit
limit 参数无效。该参数应为整数。
invalid_api_key_name
给定的 name 无效。该字段应为字符串或设置为 null。
invalid_api_key_offset
offset 参数无效。该参数应为整数。
invalid_api_key_uid
给定的 uid 无效。uid 必须遵循 uuid v4 格式。
invalid_search_attributes_to_search_on
传递给 attributesToSearchOn 的值无效。attributesToSearchOn 接受一个字符串数组，表示文档属性。提供给 attributesToSearchOn 的属性必须存在于 searchableAttributes 列表 中。
invalid_content_type
Content-Type 请求头不被 Meilisearch 支持。目前 Meilisearch 仅支持 JSON、CSV 和 NDJSON 格式。
invalid_document_csv_delimiter
csvDelimiter 参数无效。它应该是一个字符串或单个 ASCII 字符。
invalid_document_id
提供的文档标识符不符合格式要求。文档标识符必须是整数或字符串类型，且仅由字母数字字符（a-z A-Z 0-9）、连字符（-）和下划线（_）组成。
invalid_document_fields
fields 参数无效。它应该是一个字符串。
invalid_document_filter
在以下情况下会出现此错误：
filter参数无效- 对于使用 POST 端点获取文档，它应该是字符串、字符串数组或字符串数组的数组
- 对于使用 GET 端点获取文档，它应该是字符串
- 用于过滤的属性未在
filterableAttributes列表中定义 - 过滤表达式缺少运算符或运算符无效。查看支持的运算符详情
invalid_document_limit
limit 参数无效。它应该是一个整数。
invalid_document_offset
offset 参数无效。它应该是一个整数。
invalid_document_geo_field
一个或多个文档提供的 _geo 字段无效。Meilisearch 期望 _geo 是一个包含 lat 和 lng 两个字段的对象，每个字段应包含以字符串或浮点数表示的地理坐标。更多关于 _geo 的信息及问题排查方法，请参阅我们的专用指南。
invalid_facet_search_facet_name
用于 facetName 字段的属性要么不是字符串，要么未在 filterableAttributes 列表中定义。
invalid_facet_search_facet_query
提供的 facetQuery 值无效。它应该是一个字符串或 null。
invalid_index_limit
limit 参数无效。它应该是一个整数。
invalid_index_offset
offset 参数无效。它应该是一个整数。
invalid_index_uid
提供的索引格式有误，请查看我们的索引创建指南。
invalid_index_primary_key
primaryKey 字段无效。它应该是一个字符串或设置为 null。
invalid_multi_search_query_federated
多搜索查询包含 federationOptions，但顶层的 federation 对象为 null 或缺失。
invalid_multi_search_query_pagination
多搜索查询包含 page、hitsPerPage、limit 或 offset，但顶层的 federation 对象不是 null。
invalid_multi_search_query_position
federationOptions.queryPosition 不是正整数。
invalid_multi_search_weight
多搜索查询中 federated.weight 包含负值。
invalid_multi_search_queries_ranking_rules
多搜索请求中的两个或多个查询存在不兼容的结果。
invalid_multi_search_facets
federation.facetsByIndex.<INDEX_NAME> 包含的值不在可筛选属性列表中。
invalid_multi_search_sort_facet_values_by
federation.mergeFacets.sortFacetValuesBy 不是字符串或不包含允许的值。
invalid_multi_search_query_facets
当 federation 存在且非 null 时，查询数组中的某个查询包含了 facets 参数。
invalid_multi_search_merge_facets
federation.mergeFacets 不是对象或包含意外字段。
invalid_multi_search_max_values_per_facet
federation.mergeFacets.maxValuesPerFacet 不是正整数。
invalid_multi_search_facet_order
两个或多个索引对同一请求的 facet 具有不同的 faceting.sortFacetValuesBy 设置。
invalid_multi_search_facets_by_index
facetsByIndex 不是对象或包含未知字段。
invalid_multi_search_remote
federationOptions.remote 不是 network.self 且不在 network.remotes 的键中。
invalid_network_self
network 对象 中的 self 不是字符串或 null。
invalid_network_remotes
network 对象 中的 remotes 不是对象或 null。
invalid_network_url
network 对象 中的某个远程节点包含的 url 不是字符串。
invalid_network_search_api_key
network 对象 中的某个远程节点包含的 searchApiKey 不是字符串或 null。
invalid_search_attributes_to_crop
attributesToCrop 参数无效。它应该是字符串数组、字符串或设置为 null。
invalid_search_attributes_to_highlight
attributesToHighlight 参数无效。它应该是一个字符串数组、单个字符串或设为 null。
invalid_search_attributes_to_retrieve
attributesToRetrieve 参数无效。它应该是一个字符串数组、单个字符串或设为 null。
invalid_search_crop_length
cropLength 参数无效。它应该是一个整数。
invalid_search_crop_marker
cropMarker 参数无效。它应该是一个字符串或设为 null。
invalid_search_embedder
embedder 参数无效。它应该是一个字符串，对应已配置的嵌入器名称。
invalid_search_facets
此错误在以下情况发生时出现：
facets参数无效。它应该是一个字符串数组、单个字符串或设为null- 用于分面的属性未在
filterableAttributes列表中定义
invalid_search_filter
此错误在以下情况发生时出现：
filter参数的语法无效- 用于过滤的属性未在
filterableAttributes列表中定义 - 使用了保留关键字如
_geo、_geoDistance或_geoPoint作为过滤器
invalid_search_highlight_post_tag
highlightPostTag 参数无效。它应该是一个字符串。
invalid_search_highlight_pre_tag
highlightPreTag 参数无效。它应该是一个字符串。
invalid_search_hits_per_page
hitsPerPage 参数无效。它应该是一个整数。
invalid_search_hybrid_query
hybrid 参数既不是 null 也不是对象，或者是一个包含未知键的对象。
invalid_search_limit
limit 参数无效。它应该是一个整数。
invalid_search_locales
locales 参数无效。
invalid_settings_embedder
embedders 索引设置值无效。
invalid_settings_facet_search
facetSearch 索引设置值无效。
invalid_settings_localized_attributes
localizedAttributes 索引设置值无效。
invalid_search_matching_strategy
matchingStrategy 参数无效。它应该设置为 last 或 all。
invalid_search_offset
offset 参数无效。它应该是一个整数。
invalid_settings_prefix_search
prefixSearch 索引设置值无效。
invalid_search_page
page 参数无效。它应该是一个整数。
invalid_search_q
q 参数无效。它应该是一个字符串或设置为 null。
invalid_search_ranking_score_threshold
搜索或多搜索请求中的 rankingScoreThreshold 不是介于 0.0 和 1.0 之间的数字。
invalid_search_show_matches_position
showMatchesPosition 参数无效。它应该是一个布尔值或设置为 null。
invalid_search_sort
当出现以下情况时会触发此错误：
sort参数的语法无效- 用于排序的属性未在
sortableAttributes列表中定义，或设置中缺少sort排序规则 - 使用了保留关键字（如
_geo、_geoDistance、_geoRadius或_geoBoundingBox）作为筛选条件
invalid_settings_displayed_attributes
displayed attributes 的值无效。它应该是空数组、字符串数组或设置为 null。
invalid_settings_distinct_attribute
distinct attributes 的值无效。它应该是字符串或设置为 null。
invalid_settings_faceting_sort_facet_values_by
为 sortFacetValuesBy 对象提供的值不正确。可接受值为 alpha 或 count。
invalid_settings_faceting_max_values_per_facet
maxValuesPerFacet 字段的值无效。它应该是整数或设置为 null。
invalid_settings_filterable_attributes
filterable attributes 的值无效。它应该是空数组、字符串数组或设置为 null。
invalid_settings_pagination
maxTotalHits 字段的值无效。它应该是整数或设置为 null。
invalid_settings_ranking_rules
当出现以下情况时会触发此错误：
- settings payload 格式无效
- 指定了不存在的排序规则
- 自定义排序规则格式错误
- 使用了保留关键字（如
_geo、_geoDistance、_geoRadius、_geoBoundingBox或_geoPoint）作为自定义排序规则
invalid_settings_searchable_attributes
searchable attributes（可搜索属性）的值无效。它应该是一个空数组、字符串数组或设置为null。
invalid_settings_search_cutoff_ms
searchCutoffMs（搜索截止时间）的指定值无效。它应该是一个表示毫秒截止时间的整数。
invalid_settings_sortable_attributes
sortable attributes（可排序属性）的值无效。它应该是一个空数组、字符串数组或设置为null。
invalid_settings_stop_words
stop words（停用词）的值无效。它应该是一个空数组、字符串数组或设置为null。
invalid_settings_synonyms
synonyms（同义词）的值无效。它应该是一个对象或设置为null。
invalid_settings_typo_tolerance
以下情况会触发此错误：
enabled（启用状态）字段无效。它应该是一个布尔值或设置为nulldisableOnAttributes（属性禁用）字段无效。它应该是一个字符串数组或设置为nulldisableOnWords（单词禁用）字段无效。它应该是一个字符串数组或设置为nullminWordSizeForTypos（最小纠错词长）字段无效。它应该是一个整数或设置为nulloneTypo（单字符纠错）或twoTypos（双字符纠错）的值无效。它应该是一个整数或设置为null
invalid_similar_id
提供的目标文档标识符无效。文档标识符可以是整数或字符串类型，且只能包含字母数字字符（a-z A-Z 0-9）、连字符（-）和下划线（_）。
not_found_similar_id
Meilisearch 找不到目标文档。请确保目标文档标识符对应于索引中的某个文档。
invalid_similar_attributes_to_retrieve
attributesToRetrieve 参数无效。它应该是一个字符串数组、单个字符串或设为 null。
invalid_similar_embedder
embedder 参数无效。它应该是一个字符串，对应于已配置的嵌入器名称。
invalid_similar_filter
filter 参数无效或包含缺少运算符或运算符无效的过滤表达式。对于 POST 端点，过滤表达式必须是字符串、字符串数组或字符串数组的数组。对于 GET 端点，它必须是字符串。
如果用于过滤的属性未在 filterableAttributes 列表中定义，Meilisearch 也会抛出此错误。
invalid_similar_limit
limit 参数无效。它应该是一个整数。
invalid_similar_offset
offset 参数无效。它应该是一个整数。
invalid_similar_show_ranking_score
ranking_score 参数无效。它应该是一个布尔值。
invalid_similar_show_ranking_score_details
ranking_score_details 参数无效。它应该是一个布尔值。
invalid_similar_ranking_score_threshold
相似文档请求中的 rankingScoreThreshold 不是介于 0.0 和 1.0 之间的数字。
invalid_state
数据库处于无效状态。删除数据库并重新索引应该可以解决此问题。
invalid_store_file
data.ms 文件夹处于无效状态。您的 b 文件已损坏，或者 data.ms 文件夹被替换成了文件。
invalid_swap_duplicate_index_found
在交换索引请求的 indexes 数组中，某些索引被重复声明。每个索引只能声明一次。
invalid_swap_indexes
出现此错误的情况包括：
invalid_task_after_enqueued_at
afterEnqueuedAt 查询参数无效。
invalid_task_after_finished_at
afterFinishedAt 查询参数无效。
invalid_task_after_started_at
afterStartedAt 查询参数无效。
invalid_task_before_enqueued_at
beforeEnqueuedAt 查询参数无效。
invalid_task_before_finished_at
beforeFinishedAt 查询参数无效。
invalid_task_before_started_at
beforeStartedAt 查询参数无效。
invalid_task_canceled_by
canceledBy 查询参数无效。该参数应为整数。多个 uid 之间应使用逗号（,）分隔。
invalid_task_index_uids
indexUids 查询参数包含无效的索引 uid。
invalid_task_limit
limit 参数无效。该参数必须为整数。
invalid_task_statuses
请求的任务状态无效。请使用可能的值之一。
invalid_task_types
请求的任务类型无效。请使用可能的值之一。
invalid_task_uids
uids 查询参数无效。
io_error
此错误通常发生在主机系统设备空间不足或数据库没有读写权限时。
index_primary_key_no_candidate_found
主键推断失败，因为接收的文档不包含任何以 id 结尾的字段。手动指定主键，或在文档中添加以 id 结尾的字段。
malformed_payload
Content-Type 标头与请求体负载格式不匹配，或者格式无效。
missing_api_key_actions
负载中缺少 actions 字段。
missing_api_key_expires_at
负载中缺少 expiresAt 字段。
missing_api_key_indexes
负载中缺少 indexes 字段。
missing_authorization_header
此错误发生在以下情况：
- 请求的资源受 API 密钥保护，但请求头中未提供。查看我们的安全教程获取更多信息
- 您使用的授权标头与版本不匹配。v0.24 及以下版本使用
X-MEILI-API-KEY: apiKey，而 v0.25 及以上版本使用Authorization: Bearer apiKey
missing_content_type
负载缺少 Content-Type 标头。目前 Meilisearch 仅支持 JSON、CSV 和 NDJSON 格式。
missing_document_filter
该请求负载缺少 filter 字段。
missing_document_id
文档缺少必需的主键值，因此无效。请检查当前添加的文档中哪些是无效的。
missing_index_uid
请求负载缺少 uid 字段。
missing_facet_search_facet_name
facetName 参数是必需的。
missing_master_key
访问 /keys 路由前需要设置主密钥。关于启动时设置主密钥的更多信息，请参阅我们的安全教程。
missing_network_url
网络对象中的某个远程节点缺少 url 字段。
missing_payload
请求头指定了 Content-Type，但未向服务器发送请求体或请求体为空。
missing_swap_indexes
索引交换负载缺少 indexes 对象。
missing_task_filters
no_space_left_on_device
此错误在以下情况发生时出现：
- 主机系统分区达到最大容量，无法继续写入
- 任务队列达到上限，无法继续写入。您可以使用删除任务端点删除任务以继续写入操作
not_found
请求的资源未找到。
payload_too_large
发送到服务器的负载过大。查看此指南自定义 Meilisearch 接受的最大负载大小。
task_not_found
请求的任务不存在。请确保您使用了正确的 uid。
too_many_open_files
索引大批量文档（例如超过 3.5GB 的 JSON 文件）可能导致 Meilisearch 打开过多文件描述符。根据您的机器配置，这可能会达到系统默认的资源使用限制并触发 too_many_open_files 错误。在运行 Meilisearch 之前，请使用 ulimit 或类似工具提高资源消耗限制。例如，在 UNIX 环境中执行 ulimit -Sn 3000 将允许的打开文件描述符数量提升至 3000。
too_many_search_requests
您已达到并发搜索请求的限制。您可以通过重启实例并为 --experimental-search-queue-size 设置更高的值来配置此限制。
unretrievable_document
文档存在于存储中，但检索时出现错误。这可能是由于数据库处于不一致状态导致的。
vector_embedding_error
生成向量嵌入时出错。
远程联邦搜索错误
remote_bad_response
远程实例返回的响应无法被当前实例用作联邦搜索响应。
remote_bad_request
远程实例返回了 400 BAD REQUEST 响应。
remote_could_not_send_request
发送远程联邦搜索请求时出错。
remote_invalid_api_key
远程实例对此实例的请求返回了 403 FORBIDDEN 或 401 UNAUTHORIZED。配置的搜索 API 密钥可能缺失、无效或缺少必要的搜索权限。
remote_remote_error
远程实例返回了 500 INTERNAL ERROR 响应。
remote_timeout
代理未在分配时间内响应。