> For the complete documentation index, see [llms.txt](https://help.bioinsight.illumina.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.bioinsight.illumina.com/clarity-lims/clarity-lims-v6.3-and-lablink-v2.5/clarity-lims-v6.3-reference-guide/search/search-indexing-troubleshooting.md). # Search Indexing Troubleshooting This article describes known search indexing issues and the steps to resolve them. ## Keyword Fields Too Large ### Identifying the Issue If search indexing fails or stalls, check the `search-indexer` log for an error similar to the following: ``` Document contains at least one immense term in field="sample.reagentLabel.keyword" (whose UTF8 encoding is longer than the max length 32676) ``` This occurs when a sample has a large number of reagent labels whose combined values exceed Elasticsearch's keyword field size limit of 32676 bytes. ### Workaround Apply the fix using one of the two options below, depending on whether you plan to trigger a full re-index. SSH into the Clarity LIMS server. On Clarity LIMS v6.3.6 and later, authenticate to Elasticsearch before running any `curl` command. On v6.3.5 and earlier, skip the authentication section and run the `curl` commands as written. #### Authenticate to Elasticsearch (Clarity LIMS v6.3.6 and later) Starting with Clarity LIMS v6.3.6, Elasticsearch requires the `lims_indexer` service account. Unauthenticated requests return HTTP 401 Unauthorized. Add `-u lims_indexer` to every `curl` command in this article, including the commands in Option 1, Option 2, and Workaround Verification. For example: ```bash curl -u lims_indexer -X PUT "localhost:9200/_template/sample?pretty" \ -H 'Content-Type: application/json' -d '' ``` {% hint style="info" %} You shall be prompted for the `lims_indexer` service account password. Retrieve the password using [Guide to Secret Management](/clarity-lims/clarity-lims-v6.3-and-lablink-v2.5/installation/guide-to-secret-management.md) with the `app.elasticsearch.password` key. {% endhint %} #### Option 1: Apply Index Templates and Trigger a Full Re-index (Recommended) Index templates ensure the fix is applied to all newly created indexes when a full re-index is performed. Run the following commands: {% hint style="info" %} In the commands below, replace `tenant1` with the tenant ID used in your deployment. {% endhint %} **Sample index:** ```bash curl -X PUT "localhost:9200/_template/sample?pretty" \ -H 'Content-Type: application/json' -d' { "index_patterns": ["sample_tenant1_*"], "mappings": { "properties": { "reagentLabel": { "type": "text", "fields": { "keyword": {"type": "keyword", "ignore_above": 32676} } } } } }' ``` **File index:** ```bash curl -X PUT "localhost:9200/_template/file?pretty" \ -H 'Content-Type: application/json' -d' { "index_patterns": ["file_tenant1_*"], "mappings": { "properties": { "sample": { "type": "nested", "properties": { "reagentLabel": { "type": "text", "fields": { "keyword": {"type": "keyword", "ignore_above": 32676} } } } } } } }' ``` **Step index:** ```bash curl -X PUT "localhost:9200/_template/step?pretty" \ -H 'Content-Type: application/json' -d' { "index_patterns": ["step_tenant1_*"], "mappings": { "properties": { "sample": { "type": "nested", "properties": { "reagentLabel": { "type": "text", "fields": { "keyword": {"type": "keyword", "ignore_above": 32676} } } } } } } }' ``` **Container index:** ```bash curl -X PUT "localhost:9200/_template/container?pretty" \ -H 'Content-Type: application/json' -d' { "index_patterns": ["container_tenant1_*"], "mappings": { "properties": { "sample": { "type": "nested", "properties": { "reagentLabel": { "type": "text", "fields": { "keyword": {"type": "keyword", "ignore_above": 32676} } } } } } } }' ``` After running all four commands, trigger a full re-index from the Clarity LIMS administration panel. #### Option 2: Apply the Fix to Current Indexes Without a Full Re-index If you do not plan to trigger a full re-index, apply the mapping update directly to the current active indexes. {% hint style="info" %} **Clarity LIMS v6.3.6 and later:** Add `-u lims_indexer` to the `_cat/indices` and `_mapping` commands in this option. You shall be prompted for the `lims_indexer` service account password. See [Authenticate to Elasticsearch (Clarity LIMS v6.3.6 and later)](#authenticate-to-elasticsearch-clarity-lims-v636-and-later) for details. {% endhint %} 1. Identify the current index names by running: ```bash curl "localhost:9200/_cat/indices?pretty" ``` Look for indexes with names in the format `_tenant1_` (for example, `step_tenant1_1752482042957`). 2. Apply the mapping update to each affected index. The examples below are for step and sample index. **Step index** (replace `{STEP_INDEX_NAME}` with the actual index name): ```bash curl -X PUT "localhost:9200/{STEP_INDEX_NAME}/_mapping" \ -H 'Content-Type: application/json' -d' { "properties": { "sample": { "type": "nested", "properties": { "reagentLabel": { "type": "text", "fields": { "keyword": {"type": "keyword", "ignore_above": 32676} } } } } } }' ``` **Sample index** (replace `{SAMPLE_INDEX_NAME}` with the actual index name): ```bash curl -X PUT "localhost:9200/{SAMPLE_INDEX_NAME}/_mapping" \ -H 'Content-Type: application/json' -d' { "properties": { "reagentLabel": { "type": "text", "fields": { "keyword": {"type": "keyword", "ignore_above": 32676} } } } }' ``` ### Workaround Verification After applying either option, verify that the `ignore_above` setting has been applied correctly by running the following command for each affected index (replace `{INDEX_NAME}` with the actual index name): {% hint style="info" %} **Clarity LIMS v6.3.6 and later:** Add `-u lims_indexer` to the `_mappings` command. You shall be prompted for the `lims_indexer` service account password. See [Authenticate to Elasticsearch (Clarity LIMS v6.3.6 and later)](#authenticate-to-elasticsearch-clarity-lims-v636-and-later) for details. {% endhint %} ```bash curl "localhost:9200/{INDEX_NAME}/_mappings/?pretty" ``` In the response, locate the `reagentLabel` field and confirm that `"ignore_above": 32676` is present: ```json "reagentLabel": { "type": "text", "fields": { "keyword": { "type": "keyword", "ignore_above": 32676 } } } ``` {% hint style="info" %} If you applied Option 1 (index templates with full re-index), verify the mapping on the newly created index after the re-index completes. If you applied Option 2 (current index mapping update), verify the mapping on the existing index immediately after running the update command. {% endhint %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://help.bioinsight.illumina.com/clarity-lims/clarity-lims-v6.3-and-lablink-v2.5/clarity-lims-v6.3-reference-guide/search/search-indexing-troubleshooting.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.