Error codes

Consult this page for an exhaustive list of errors you may encounter when using the Meilisearch API.

This page is an exhaustive list of Meilisearch API errors.

api_key_already_exists

A key with this uid already exists.

api_key_not_found

The requested API key could not be found.

bad_request

The request is invalid, check the error message for more information.

batch_not_found

The requested batch does not exist. Please ensure that you are using the correct uid.

database_size_limit_reached

The requested database has reached its maximum size.

document_fields_limit_reached

A document exceeds the maximum limit of 65,535 fields.

document_not_found

The requested document can’t be retrieved. Either it doesn’t exist, or the database was left in an inconsistent state.

dump_process_failed

An error occurred during the dump creation process. The task was aborted.

facet_search_disabled

The /facet-search route has been queried while the facetSearch index setting is set to false.

feature_not_enabled

You have tried using an experimental feature without activating it.

immutable_api_key_actions

The actions field of an API key cannot be modified.

immutable_api_key_created_at

The createdAt field of an API key cannot be modified.

immutable_api_key_expires_at

The expiresAt field of an API key cannot be modified.

immutable_api_key_indexes

The indexes field of an API key cannot be modified.

immutable_api_key_key

The key field of an API key cannot be modified.

immutable_api_key_uid

The uid field of an API key cannot be modified.

immutable_api_key_updated_at

The updatedAt field of an API key cannot be modified.

immutable_index_uid

The uid field of an index cannot be modified.

immutable_index_updated_at

The updatedAt field of an index cannot be modified.

index_already_exists

An index with this uid already exists, check out our guide on index creation.

index_creation_failed

An error occurred while trying to create an index, check out our guide on index creation.

index_not_found

An index with this uid was not found, check out our guide on index creation.

index_primary_key_already_exists

The requested index already has a primary key that cannot be changed.

index_primary_key_multiple_candidates_found

Primary key inference failed because the received documents contain multiple fields ending with id. Use the update index endpoint to manually set a primary key.

internal

Meilisearch experienced an internal error. Check the error message, and open an issue if necessary.

invalid_api_key

The requested resources are protected with an API key. The provided API key is invalid. Read more about it in our security tutorial.

invalid_api_key_actions

The actions field for the provided API key resource is invalid. It should be an array of strings representing action names.

invalid_api_key_description

The description field for the provided API key resource is invalid. It should either be a string or set to null.

invalid_api_key_expires_at

The expiresAt field for the provided API key resource is invalid. It should either show a future date or datetime in the RFC 3339 format or be set to null.

invalid_api_key_indexes

The indexes field for the provided API key resource is invalid. It should be an array of strings representing index names.

invalid_api_key_limit

The limit parameter is invalid. It should be an integer.

invalid_api_key_name

The given name is invalid. It should either be a string or set to null.

invalid_api_key_offset

The offset parameter is invalid. It should be an integer.

invalid_api_key_uid

The given uid is invalid. The uid must follow the uuid v4 format.

invalid_search_attributes_to_search_on

The value passed to attributesToSearchOn is invalid. attributesToSearchOn accepts an array of strings indicating document attributes. Attributes given to attributesToSearchOn must be present in the searchableAttributes list.

invalid_content_type

The Content-Type header is not supported by Meilisearch. Currently, Meilisearch only supports JSON, CSV, and NDJSON.

invalid_document_csv_delimiter

The csvDelimiter parameter is invalid. It should either be a string or a single ASCII character.

invalid_document_id

The provided document identifier does not meet the format requirements. A document identifier must be of type integer or string, composed only of alphanumeric characters (a-z A-Z 0-9), hyphens (-), and underscores (_).

invalid_document_fields

The fields parameter is invalid. It should be a string.

invalid_document_filter

This error occurs if:

• The filter parameter is invalid
  • It should be a string, array of strings, or array of array of strings for the get documents with POST endpoint
  • It should be a string for the get documents with GET endpoint
• The attribute used for filtering is not defined in the filterableAttributes list
• The filter expression has a missing or invalid operator. Read more about our supported operators

invalid_document_limit

The limit parameter is invalid. It should be an integer.

invalid_document_offset

The offset parameter is invalid. It should be an integer.

invalid_document_geo_field

The provided _geo field of one or more documents is invalid. Meilisearch expects _geo to be an object with two fields, lat and lng, each containing geographic coordinates expressed as a string or floating point number. Read more about _geo and how to troubleshoot it in our dedicated guide.

invalid_facet_search_facet_name

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

invalid_facet_search_facet_query

The provided value for facetQuery is invalid. It should either be a string or null.

invalid_index_limit

The limit parameter is invalid. It should be an integer.

invalid_index_offset

The offset parameter is invalid. It should be an integer.

invalid_index_uid

There is an error in the provided index format, check out our guide on index creation.

invalid_index_primary_key

The primaryKey field is invalid. It should either be a string or set to null.

invalid_multi_search_query_federated

A multi-search query includes federationOptions but the top-level federation object is null or missing.

invalid_multi_search_query_pagination

A multi-search query contains page, hitsPerPage, limit or offset, but the top-level federation object is not null.

invalid_multi_search_query_position

federationOptions.queryPosition is not a positive integer.

invalid_multi_search_weight

A multi-search query contains a negative value for federated.weight.

invalid_multi_search_queries_ranking_rules

Two or more queries in a multi-search request have incompatible results.

invalid_multi_search_facets

federation.facetsByIndex.<INDEX_NAME> contains a value that is not in the filterable attributes list.

invalid_multi_search_sort_facet_values_by

federation.mergeFacets.sortFacetValuesBy is not a string or doesn’t have one of the allowed values.

invalid_multi_search_query_facets

A query in the queries array contains facets when federation is present and non-null.

invalid_multi_search_merge_facets

federation.mergeFacets is not an object or contains unexpected fields.

invalid_multi_search_max_values_per_facet

federation.mergeFacets.maxValuesPerFacet is not a positive integer.

invalid_multi_search_facet_order

Two or more indexes have a different faceting.sortFacetValuesBy for the same requested facet.

invalid_multi_search_facets_by_index

facetsByIndex is not an object or contains unknown fields.

invalid_multi_search_remote

federationOptions.remote is not network.self and is not a key in network.remotes.

invalid_network_self

The network object contains a self that is not a string or null.

invalid_network_remotes

The network object contains a remotes that is not an object or null.

invalid_network_url

One of the remotes in the network object contains a url that is not a string.

invalid_network_search_api_key

One of the remotes in the network object contains a searchApiKey that is not a string or null.

invalid_search_attributes_to_crop

The attributesToCrop parameter is invalid. It should be an array of strings, a string, or set to null.

invalid_search_attributes_to_highlight

The attributesToHighlight parameter is invalid. It should be an array of strings, a string, or set to null.

invalid_search_attributes_to_retrieve

The attributesToRetrieve parameter is invalid. It should be an array of strings, a string, or set to null.

invalid_search_crop_length

The cropLength parameter is invalid. It should be an integer.

invalid_search_crop_marker

The cropMarker parameter is invalid. It should be a string or set to null.

invalid_search_embedder

embedder is invalid. It should be a string corresponding to the name of a configured embedder.

invalid_search_facets

This error occurs if:

• The facets parameter is invalid. It should be an array of strings, a string, or set to null
• The attribute used for faceting is not defined in the filterableAttributes list

invalid_search_filter

This error occurs if:

• The syntax for the filter parameter is invalid
• The attribute used for filtering is not defined in the filterableAttributes list
• A reserved keyword like _geo, _geoDistance, or _geoPoint is used as a filter

invalid_search_highlight_post_tag

The highlightPostTag parameter is invalid. It should be a string.

invalid_search_highlight_pre_tag

The highlightPreTag parameter is invalid. It should be a string.

invalid_search_hits_per_page

The hitsPerPage parameter is invalid. It should be an integer.

invalid_search_hybrid_query

The hybrid parameter is neither null nor an object, or it is an object with unknown keys.

invalid_search_limit

The limit parameter is invalid. It should be an integer.

invalid_search_locales

The locales parameter is invalid.

invalid_settings_embedder

The embedders index setting value is invalid.

invalid_settings_facet_search

The facetSearch index setting value is invalid.

invalid_settings_localized_attributes

The localizedAttributes index setting value is invalid.

invalid_search_matching_strategy

The matchingStrategy parameter is invalid. It should either be set to last or all.

invalid_search_offset

The offset parameter is invalid. It should be an integer.

invalid_settings_prefix_search

The prefixSearch index setting value is invalid.

invalid_search_page

The page parameter is invalid. It should be an integer.

invalid_search_q

The q parameter is invalid. It should be a string or set to null

invalid_search_ranking_score_threshold

The rankingScoreThreshold in a search or multi-search request is not a number between 0.0 and 1.0.

invalid_search_show_matches_position

The showMatchesPosition parameter is invalid. It should either be a boolean or set to null.

invalid_search_sort

This error occurs if:

• The syntax for the sort parameter is invalid
• The attribute used for sorting is not defined in the sortableAttributes list or the sort ranking rule is missing from the settings
• A reserved keyword like _geo, _geoDistance, _geoRadius, or _geoBoundingBox is used as a filter

invalid_settings_displayed_attributes

The value of displayed attributes is invalid. It should be an empty array, an array of strings, or set to null.

invalid_settings_distinct_attribute

The value of distinct attributes is invalid. It should be a string or set to null.

invalid_settings_faceting_sort_facet_values_by

The value provided for the sortFacetValuesBy object is incorrect. The accepted values are alpha or count.

invalid_settings_faceting_max_values_per_facet

The value for the maxValuesPerFacet field is invalid. It should either be an integer or set to null.

invalid_settings_filterable_attributes

The value of filterable attributes is invalid. It should be an empty array, an array of strings, or set to null.

invalid_settings_pagination

The value for the maxTotalHits field is invalid. It should either be an integer or set to null.

invalid_settings_ranking_rules

This error occurs if:

• The settings payload has an invalid format
• A non-existent ranking rule is specified
• A custom ranking rule is malformed
• A reserved keyword like _geo, _geoDistance, _geoRadius, _geoBoundingBox, or _geoPoint is used as a custom ranking rule

invalid_settings_searchable_attributes

The value of searchable attributes is invalid. It should be an empty array, an array of strings or set to null.

invalid_settings_search_cutoff_ms

The specified value for `searchCutoffMs is invalid. It should be an integer indicating the cutoff in milliseconds.

invalid_settings_sortable_attributes

The value of sortable attributes is invalid. It should be an empty array, an array of strings or set to null.

invalid_settings_stop_words

The value of stop words is invalid. It should be an empty array, an array of strings or set to null.

invalid_settings_synonyms

The value of the synonyms is invalid. It should either be an object or set to null.

invalid_settings_typo_tolerance

This error occurs if:

• The enabled field is invalid. It should either be a boolean or set to null
• The disableOnAttributes field is invalid. It should either be an array of strings or set to null
• The disableOnWords field is invalid. It should either be an array of strings or set to null
• The minWordSizeForTypos field is invalid. It should either be an integer or set to null
• The value of either oneTypo or twoTypos is invalid. It should either be an integer or set to null

invalid_similar_id

The provided target document identifier is invalid. A document identifier can be of type integer or string, only composed of alphanumeric characters (a-z A-Z 0-9), hyphens (-) and underscores (_).

not_found_similar_id

Meilisearch could not find the target document. Make sure your target document identifier corresponds to a document in your index.

invalid_similar_attributes_to_retrieve

attributesToRetrieve is invalid. It should be an array of strings, a string, or set to null.

invalid_similar_embedder

embedder is invalid. It should be a string corresponding to the name of a configured embedder.

invalid_similar_filter

filter is invalid or contains a filter expression with a missing or invalid operator. Filter expressions must be a string, array of strings, or array of array of strings for the POST endpoint. It must be a string for the GET endpoint.

Meilisearch also throws this error if the attribute used for filtering is not defined in the filterableAttributes list.

invalid_similar_limit

limit is invalid. It should be an integer.

invalid_similar_offset

offset is invalid. It should be an integer.

invalid_similar_show_ranking_score

ranking_score is invalid. It should be a boolean.

invalid_similar_show_ranking_score_details

ranking_score_details is invalid. It should be a boolean.

invalid_similar_ranking_score_threshold

The rankingScoreThreshold in a similar documents request is not a number between 0.0 and 1.0.

invalid_state

The database is in an invalid state. Deleting the database and re-indexing should solve the problem.

invalid_store_file

The data.ms folder is in an invalid state. Your b file is corrupted or the data.ms folder has been replaced by a file.

invalid_swap_duplicate_index_found

The indexes used in the indexes array for a swap index request have been declared multiple times. You must declare each index only once.

invalid_swap_indexes

This error happens if:

• The payload doesn’t contain exactly two index uids for a swap operation
• The payload contains an invalid index name in the indexes array

invalid_task_after_enqueued_at

The afterEnqueuedAt query parameter is invalid.

invalid_task_after_finished_at

The afterFinishedAt query parameter is invalid.

invalid_task_after_started_at

The afterStartedAt query parameter is invalid.

invalid_task_before_enqueued_at

The beforeEnqueuedAt query parameter is invalid.

invalid_task_before_finished_at

The beforeFinishedAt query parameter is invalid.

invalid_task_before_started_at

The beforeStartedAt query parameter is invalid.

invalid_task_canceled_by

The canceledBy query parameter is invalid. It should be an integer. Multiple uids should be separated by commas (,).

invalid_task_index_uids

The indexUids query parameter contains an invalid index uid.

invalid_task_limit

The limit parameter is invalid. It must be an integer.

invalid_task_statuses

The requested task status is invalid. Please use one of the possible values.

invalid_task_types

The requested task type is invalid. Please use one of the possible values.

invalid_task_uids

The uids query parameter is invalid.

io_error

This error generally occurs when the host system has no space left on the device or when the database doesn’t have read or write access.

index_primary_key_no_candidate_found

Primary key inference failed as the received documents do not contain any fields ending with id. Manually designate the primary key, or add some field ending with id to your documents.

malformed_payload

The Content-Type header does not match the request body payload format or the format is invalid.

missing_api_key_actions

The actions field is missing from payload.

missing_api_key_expires_at

The expiresAt field is missing from payload.

missing_api_key_indexes

The indexes field is missing from payload.

missing_authorization_header

This error happens if:

• The requested resources are protected with an API key that was not provided in the request header. Check our security tutorial for more information
• You are using the wrong authorization header for your version. v0.24 and below use X-MEILI-API-KEY: apiKey, whereas v0.25 and above use Authorization: Bearer apiKey

missing_content_type

The payload does not contain a Content-Type header. Currently, Meilisearch only supports JSON, CSV, and NDJSON.

missing_document_filter

This payload is missing the filter field.

missing_document_id

A document does not contain any value for the required primary key, and is thus invalid. Check documents in the current addition for the invalid ones.

missing_index_uid

The payload is missing the uid field.

missing_facet_search_facet_name

The facetName parameter is required.

missing_master_key

You need to set a master key before you can access the /keys route. Read more about setting a master key at launch in our security tutorial.

missing_network_url

One of the remotes in the network object does not contain the url field.

missing_payload

The Content-Type header was specified, but no request body was sent to the server or the request body is empty.

missing_swap_indexes

The index swap payload is missing the indexes object.

missing_task_filters

The cancel tasks and delete tasks endpoints require one of the available query parameters.

no_space_left_on_device

This error occurs if:

• The host system partition reaches its maximum capacity and can no longer accept writes
• The tasks queue reaches its limit and can no longer accept writes. You can delete tasks using the delete tasks endpoint to continue write operations

not_found

The requested resources could not be found.

payload_too_large

The payload sent to the server was too large. Check out this guide to customize the maximum payload size accepted by Meilisearch.

task_not_found

The requested task does not exist. Please ensure that you are using the correct uid.

too_many_open_files

Indexing a large batch of documents, such as a JSON file over 3.5GB in size, can result in Meilisearch opening too many file descriptors. Depending on your machine, this might reach your system’s default resource usage limits and trigger the too_many_open_files error. Use ulimit or a similar tool to increase resource consumption limits before running Meilisearch. For example, call ulimit -Sn 3000 in a UNIX environment to raise the number of allowed open file descriptors to 3000.

too_many_search_requests

You have reached the limit of concurrent search requests. You may configure it by relaunching your instance and setting a higher value to --experimental-search-queue-size.

unretrievable_document

The document exists in store, but there was an error retrieving it. This probably comes from an inconsistent state in the database.

vector_embedding_error

Error while generating embeddings.

Remote federated search errors

remote_bad_response

The remote instance answered with a response that this instance could not use as a federated search response.

remote_bad_request

The remote instance answered with 400 BAD REQUEST.

remote_could_not_send_request

There was an error while sending the remote federated search request.

remote_invalid_api_key

The remote instance answered with 403 FORBIDDEN or 401 UNAUTHORIZED to this instance’s request. The configured search API key is either missing, invalid, or lacks the required search permission.

remote_remote_error

The remote instance answered with 500 INTERNAL ERROR.

remote_timeout

The proxy did not answer in the allocated time.