This error occurs when attempting to sort by a field that has no mapping defined in the Elasticsearch index. The field either doesn't exist, hasn't been indexed yet, or is defined as a text type which cannot be used for sorting.
Elasticsearch throws this QueryShardException when you attempt to sort search results by a field that doesn't have a mapping in the index. Mappings in Elasticsearch define the data type and structure of fields, and sorting requires Elasticsearch to know the field's type to properly order results. This error typically appears in three scenarios: the field was never mapped because no documents containing it have been indexed yet, the field name is misspelled in your sort query, or the field is mapped as a text type rather than a sortable type like keyword or numeric. Text fields are analyzed and broken into tokens for full-text search, making them unsuitable for sorting operations that require exact field values. The error message will indicate which specific field caused the problem, helping you identify whether it's a mapping issue, a query typo, or a type mismatch between what you're trying to sort and how the field is actually defined.
Check if the field you're trying to sort on actually exists in your index mapping:
GET /your-index/_mappingLook for the field name in the response. If it's not present, the field hasn't been mapped yet. If you're sorting across multiple indices, check each one:
GET /index1,index2/_mapping/field/your-field-nameThis will show you whether the field exists in each index and how it's mapped.
If the field doesn't exist in some indices but you still want the query to work, use the unmapped_type parameter to tell Elasticsearch how to treat unmapped fields:
GET /your-index/_search
{
"query": {
"match_all": {}
},
"sort": [
{
"your-field": {
"order": "desc",
"unmapped_type": "long"
}
}
]
}For keyword fields, use "unmapped_type": "keyword". For dates, use "unmapped_type": "date". This tells Elasticsearch to treat documents in indices without this field as if they have no value for it, rather than failing the query.
If the field should exist but doesn't, add it to your index mapping. For a new index:
PUT /your-index
{
"mappings": {
"properties": {
"your-field": {
"type": "keyword"
}
}
}
}For existing indices, you can add new fields to the mapping:
PUT /your-index/_mapping
{
"properties": {
"your-field": {
"type": "keyword"
}
}
}Choose the appropriate type: keyword for exact-value sorting, long/integer for numbers, date for timestamps. Never use text for fields you need to sort on.
If you're trying to sort on a text field, you cannot sort on the analyzed text directly. Most text fields have a .keyword subfield created automatically for sorting and aggregations:
GET /your-index/_search
{
"query": {
"match_all": {}
},
"sort": [
{
"your-field.keyword": {
"order": "asc"
}
}
]
}Check your mapping to confirm the .keyword subfield exists. If it doesn't, you can add it:
PUT /your-index/_mapping
{
"properties": {
"your-field": {
"type": "text",
"fields": {
"keyword": {
"type": "keyword",
"ignore_above": 256
}
}
}
}
}If you've corrected the mapping but documents were already indexed with incorrect types, you need to reindex:
POST /_reindex
{
"source": {
"index": "your-old-index"
},
"dest": {
"index": "your-new-index"
}
}Then use an index alias to switch from the old to new index without downtime:
POST /_aliases
{
"actions": [
{ "remove": { "index": "your-old-index", "alias": "your-alias" } },
{ "add": { "index": "your-new-index", "alias": "your-alias" } }
]
}This ensures all documents are properly indexed according to the corrected mapping.
When working with multi-index queries (using wildcards or multiple index names), remember that Elasticsearch checks all targeted indices for field mappings. If any index is missing the field, use unmapped_type to prevent query failures.
For optimal sorting performance, avoid text fields entirely. Text fields are analyzed into tokens, making them memory-intensive and slow for sorting. Always use keyword, numeric, or date types for fields you'll sort or aggregate on.
If you're using dynamic mapping and want to ensure certain fields are always mapped correctly, create index templates that define mappings for field patterns:
PUT /_index_template/your-template
{
"index_patterns": ["logs-*"],
"template": {
"mappings": {
"properties": {
"timestamp": { "type": "date" },
"status": { "type": "keyword" },
"message": {
"type": "text",
"fields": {
"keyword": { "type": "keyword", "ignore_above": 256 }
}
}
}
}
}
}This ensures new indices matching the pattern automatically get proper mappings without manual intervention.
In Elasticsearch 7.x and later, the unmapped_type parameter is particularly important when dealing with index patterns that might include indices created at different times or with different schemas. It allows queries to be more resilient to mapping variations across indices.
IndexNotFoundException: no such index [index_name]
How to fix "IndexNotFoundException: no such index [index_name]" in Elasticsearch
DocumentMissingException: [index][type][id]: document missing
DocumentMissingException: Document missing
ParsingException: Unknown key for a START_OBJECT in [query]
How to fix "ParsingException: Unknown key for a START_OBJECT in [query]" in Elasticsearch
AggregationExecutionException: Aggregation [agg_name] does not support sampling
How to fix "AggregationExecutionException: Aggregation [agg_name] does not support sampling" in Elasticsearch
ScriptException: compile error
ScriptException: compile error