How to fix RoutingMissingException: routing is required for [index]/[type]/[id] in Elasticsearch

ElasticsearchINTERMEDIATEMEDIUMUpdated Dec 22, 2025· 136 views

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.

Quick fix

Fixes RoutingMissingException: routing is required for [index]/[type]/[id]

GET /your-index/_mapping
  1. Check if routing is required in index mapping
  2. Add routing parameter to index operations
  3. Include routing in GET, UPDATE, and DELETE requests
  4. Configure automatic routing extraction (optional)
elasticsearch — error
GET /your-index/_mapping
RoutingMissingException: routing is required for [index]/[type]/[id]

What this error means

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.

Typical symptoms

  • Document indexing fails with RoutingMissingException error
  • GET, UPDATE, or DELETE requests return 400 status with routing_missing_exception
  • Error message includes the index name, type, and document ID being accessed
  • Operations succeed when routing parameter is added to the request

Common causes

  1. Index mapping has _routing.required set to true but request omits routing parameter
  2. Application code does not include routing value in Elasticsearch client calls
  3. Index was reconfigured to require routing after documents were already indexed without it
  4. Routing parameter is being sent with incorrect parameter name or in wrong location
  5. Client library version does not properly support routing parameters

How to fix "RoutingMissingException: routing is required for [index]/[type]/[id]"

1Check if routing is required in index mapping

First, verify that your index actually has routing configured as required:

bash
GET /your-index/_mapping

Look for the _routing field configuration:

json
{
  "your-index": {
    "mappings": {
      "_routing": {
        "required": true
      }
    }
  }
}

If required is set to true, you must provide routing with all requests.

2Add routing parameter to index operations

When indexing a document, include the routing parameter in the query string:

bash
PUT /your-index/_doc/document-id?routing=user-123
{
  "field": "value"
}

Or using the Elasticsearch client libraries:

JavaScript/Node.js:

javascript
await client.index({
  index: 'your-index',
  id: 'document-id',
  routing: 'user-123',
  body: {
    field: 'value'
  }
});

Python:

python
es.index(
    index='your-index',
    id='document-id',
    routing='user-123',
    body={'field': 'value'}
)

Java:

java
IndexRequest request = new IndexRequest("your-index")
    .id("document-id")
    .routing("user-123")
    .source(jsonMap);
3Include routing in GET, UPDATE, and DELETE requests

The same routing value must be provided for all operations on the document:

GET:

bash
GET /your-index/_doc/document-id?routing=user-123

UPDATE:

bash
POST /your-index/_update/document-id?routing=user-123
{
  "doc": {
    "field": "new-value"
  }
}

DELETE:

bash
DELETE /your-index/_doc/document-id?routing=user-123

Using client libraries, add the routing parameter to each method call just like with indexing.

4Configure automatic routing extraction (optional)

If you want Elasticsearch to automatically extract routing from a document field, configure the path parameter when creating the index:

json
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.

5Remove routing requirement if not needed

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:

json
PUT /your-index-new
{
  "mappings": {
    "properties": {
      // your field mappings
    }
  }
}

2. Reindex data from the old index:

json
POST _reindex
{
  "source": {
    "index": "your-index"
  },
  "dest": {
    "index": "your-index-new"
  }
}

3. Delete the old index and create an alias:

bash
DELETE /your-index
POST /_aliases
{
  "actions": [
    { "add": { "index": "your-index-new", "alias": "your-index" } }
  ]
}

Note: Routing configuration cannot be changed on an existing index.

Advanced notes

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:

json
POST _bulk
{ "index": { "_index": "your-index", "_id": "1", "routing": "user-123" } }
{ "field": "value1" }
{ "index": { "_index": "your-index", "_id": "2", "routing": "user-123" } }
{ "field": "value2" }

Frequently asked questions

What does "RoutingMissingException: routing is required for [index]/[type]/[id]" mean?
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.
How do I fix "RoutingMissingException: routing is required for [index]/[type]/[id]"?
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.
What causes "RoutingMissingException: routing is required for [index]/[type]/[id]"?
Index mapping has _routing.required set to true but request omits routing parameter Application code does not include routing value in Elasticsearch client calls Index was reconfigured to require routing after documents were already indexed without it
Is the "RoutingMissingException: routing is required for [index]/[type]/[id]" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading