This error occurs when an index mapping requires a routing value for all CRUD operations, but the request does not provide one. The routing parameter determines which shard stores a document.
The RoutingMissingException error indicates that your Elasticsearch index has been configured with routing set as required in the mapping, but your index, get, update, or delete request does not include the necessary routing parameter. Elasticsearch uses routing to determine which shard should store or retrieve a document using the formula: shard_number = hash(routing) % number_of_primary_shards. By default, Elasticsearch uses the document's _id as the routing value. However, when you configure custom routing as required in the index mapping, you must explicitly provide a routing value with every operation. This configuration is commonly used to ensure that related documents are stored on the same shard for performance optimization, such as keeping all documents for a specific user or tenant together. When routing is required but not provided, Elasticsearch rejects the operation to prevent data distribution issues.
First, verify that your index actually has routing configured as required:
GET /your-index/_mappingLook for the _routing field configuration:
{
"your-index": {
"mappings": {
"_routing": {
"required": true
}
}
}
}If required is set to true, you must provide routing with all requests.
When indexing a document, include the routing parameter in the query string:
PUT /your-index/_doc/document-id?routing=user-123
{
"field": "value"
}Or using the Elasticsearch client libraries:
JavaScript/Node.js:
await client.index({
index: 'your-index',
id: 'document-id',
routing: 'user-123',
body: {
field: 'value'
}
});Python:
es.index(
index='your-index',
id='document-id',
routing='user-123',
body={'field': 'value'}
)Java:
IndexRequest request = new IndexRequest("your-index")
.id("document-id")
.routing("user-123")
.source(jsonMap);The same routing value must be provided for all operations on the document:
GET:
GET /your-index/_doc/document-id?routing=user-123UPDATE:
POST /your-index/_update/document-id?routing=user-123
{
"doc": {
"field": "new-value"
}
}DELETE:
DELETE /your-index/_doc/document-id?routing=user-123Using client libraries, add the routing parameter to each method call just like with indexing.
If you want Elasticsearch to automatically extract routing from a document field, configure the path parameter when creating the index:
PUT /your-index
{
"mappings": {
"_routing": {
"required": true,
"path": "userId"
},
"properties": {
"userId": { "type": "keyword" },
"name": { "type": "text" }
}
}
}With this configuration, Elasticsearch will automatically use the userId field value as the routing parameter. Note that this requires additional parsing and is slightly slower than explicit routing.
If routing was enabled by mistake or is no longer needed, you'll need to reindex your data to a new index without the routing requirement:
1. Create a new index without routing requirement:
PUT /your-index-new
{
"mappings": {
"properties": {
// your field mappings
}
}
}2. Reindex data from the old index:
POST _reindex
{
"source": {
"index": "your-index"
},
"dest": {
"index": "your-index-new"
}
}3. Delete the old index and create an alias:
DELETE /your-index
POST /_aliases
{
"actions": [
{ "add": { "index": "your-index-new", "alias": "your-index" } }
]
}Note: Routing configuration cannot be changed on an existing index.
Routing and Shard Distribution: When using custom routing, be careful to choose routing values that distribute documents evenly across shards. If you route all documents by a field with few unique values (e.g., a boolean field), you may create shard imbalance where some shards are much larger than others, degrading performance.
Partitioned Indices: When using partitioned indices with index.routing_partition_size set, all mappings must have _routing marked as required. This ensures predictable document distribution across the partition.
Search Performance: Custom routing can significantly improve search performance when you can filter by the routing value. If you search for documents with routing=user-123, Elasticsearch only queries the single shard containing that user's data instead of all shards.
Routing Value Immutability: Once a document is indexed with a specific routing value, you cannot change it. To change routing, you must delete and reindex the document with the new routing value.
Bulk Operations: For bulk operations, include routing in each individual action within the bulk request:
POST _bulk
{ "index": { "_index": "your-index", "_id": "1", "routing": "user-123" } }
{ "field": "value1" }
{ "index": { "_index": "your-index", "_id": "2", "routing": "user-123" } }
{ "field": "value2" }QueryShardException: No mapping found for [field] in order to sort on
How to fix "QueryShardException: No mapping found for field in order to sort on" in Elasticsearch
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