Skip to main content
search
Error Logs

Error Log: Illegal_argument_exception – “Text fields are not optimised…”

By November 19, 2025No Comments

Error Log: This is another common root_cause for a query failure.
JSON

{
  "error": {
    "root_cause": [
      {
        "type": "illegal_argument_exception",
        "reason": "Text fields are not optimised for operations that require per-document field data like aggregations and sorting, therefore these operations are disabled by default. Please use a keyword field instead."
      }
    ],
    // ...
  },
  "status": 400
}

Why… is this happening? This error is a fundamental concept in OpenSearch. You are trying to sort, aggregate (group by), or run a script on a field that is mapped as text.

  • text fields are for full-text search. They are analyzed, meaning a string like "OpenSearch-Log-1" is broken into tokens: ["opensearch", "log", "1"]. This is great for searching for “log” but makes it impossible to sort by the original string.
  • keyword fields are for exact-value operations. They are not analyzed. The string "OpenSearch-Log-1" is stored as that single, exact value. This is what you must use for sorting, aggregations, and exact-match filters.

OpenSearch disables this operation by default because trying to sort or aggregate on an analyzed text field would load a massive amount of data into memory (called “fielddata”) and likely crash your node.

Best Practice:

1. Use the .keyword Field: This is the fix 99% of the time. By default, OpenSearch (with the standard template) creates a .keyword sub-field for your text fields. If your field is my_field, change your query to sort or aggregate on my_field.keyword.

2. Check Your Mapping: Run GET /my-index/_mapping in Dev Tools. Find your field. You will probably see:

JSON

"my_field": {
  "type": "text",
  "fields": {
    "keyword": { "type": "keyword" } // <-- This is what you want
  }
}

3. Fix Your Mapping (if .keyword is missing): If that fields block doesn’t exist, you must create a new index with the correct mapping (an index template is best for this) and re-index your old data. You cannot add this mapping to existing data.

4. Never Enable fielddata=true: You may see advice to “fix” this by setting fielddata=true on your text field. Do not do this. This is a “memory bomb” that will likely cause CircuitBreakingExceptions and node instability. Always use a keyword field instead.

What else can I do? Confused about text vs. keyword, mappings, or how to re-index your data? This is a core part of OpenSearch, and the community is here to help. For in-depth help with your data modeling, contact us in The OpenSearch Slack Channel in #General.

Author