Error log: “Fielddata is disabled on text fields by default”

Error log: You see this error as the root_cause when a query attempts to sort, aggregate, or access a text field’s raw values.

JSON

None
{

  "error": {

    "root_cause": [

      {

        "type": "illegal_argument_exception",

        "reason": "Fielddata is disabled on text fields by default. 

                   Set fielddata=true on [your_field_name] in order 

                   to load fielddata in memory..."

      }

    ], ...

  },

  "status": 400

}

Why… is this happening? This error is OpenSearch actively protecting you from crashing your cluster.

• text fields are analyzed (e.g., "Quick Brown Fox" becomes ["quick", "brown", "fox"]).
• To sort or aggregate on this field, OpenSearch would have to load all unique tokens for all documents into the JVM heap. This is called fielddata.
• For a text field, this operation is memory-intensive, rarely provides the result you want (you’d be sorting on “brown”, “fox”, “quick”, not “Quick Brown Fox”), and can easily cause an OutOfMemoryError.

Therefore, OpenSearch disables this by default. The error message tells you how to enable it (Set fielddata=true), but this is a trap!

Best practice:

1. DO NOT SET fielddata=true! This is the wrong solution 99.9% of the time. It is a “memory bomb” that will lead to CircuitBreakingExceptions and node instability.
2. The real fix: use a .keyword field. This is what you almost always want. keyword fields are not analyzed and store the exact original string (e.g., "Quick Brown Fox"). They are optimized for sorting and aggregations.
3. Check your mapping: By default, most text fields have a .keyword sub-field.
   • Your query (broken): {"sort": "my_field"}
   • Your query (fixed): {"sort": "my_field.keyword"}
4. Fix your mapping: If your index mapping doesn’t have a .keyword sub-field, you must re-create the index with an index template that defines one, and then re-index your data.

What else can I do? Confused about text vs. keyword? This is the single most important mapping concept in OpenSearch. Ask the community for help with your mappings or contact us in The OpenSearch Slack Channel in #General.