How to fix BulkItemResponse: failed to execute bulk item (index) in Elasticsearch

ElasticsearchINTERMEDIATEMEDIUMUpdated Dec 22, 2025· 185 views

This error occurs when Elasticsearch fails to process one or more operations in a bulk request. The bulk API allows multiple index, create, update, and delete operations in a single request, but individual items can fail due to document conflicts, missing indices, permission issues, or malformed data.

Quick fix

Fixes BulkItemResponse: failed to execute bulk item (index)

// Example bulk request
POST /_bulk?filter_path=items.*.error
{ "index": { "_index": "my-index", "_id": "1" } }
{ "title": "Test document" }
{ "index": { "_index": "my-index", "_id": "2" } }
{ "title": "Another document" }

// Response showing only errors
{
  "items": [
    {
      "index": {
        "error": {
          "type": "document_missing_exception",
          "reason": "[_doc][1]: document missing",
          "index_uuid": "abc123",
          "shard": "0",
          "index": "my-index"
        }
      }
    }
  ]
}
  1. Check the bulk response for detailed error information
  2. Verify index existence and permissions
  3. Validate document structure and data types
  4. Handle version conflicts and document existence
elasticsearch — error
// Example bulk request
POST /_bulk?filter_path=items.*.error
{ "index": { "_index": "my-index", "_id": "1" } }
{ "title": "Test document" }
{ "index": { "_index": "my-index", "_id": "2" } }
{ "title": "Another document" }
// Response showing only errors
{
  "items": [
    {
      "index": {
        "error": {
          "type": "document_missing_exception",
          "reason": "[_doc][1]: document missing",
          "index_uuid": "abc123",
          "shard": "0",
          "index": "my-index"
        }
      }
    }
  ]
}
BulkItemResponse: failed to execute bulk item (index)

What this error means

The "BulkItemResponse: failed to execute bulk item (index)" error indicates that one or more indexing operations within a bulk request failed to execute successfully. Elasticsearch's bulk API processes multiple operations in a single HTTP request for efficiency, but each operation is executed independently. When an individual operation fails (like an index action), the overall bulk request may still partially succeed, but the response will include detailed error information for each failed item. This error typically appears in the response body when you inspect the bulk API results. Each failed operation will have an error object containing the specific failure reason, error type, and sometimes additional metadata about what went wrong. The bulk API is designed to be fault-tolerant - it continues processing subsequent operations even if some fail, but you need to check the response to identify which specific items failed and why. Common scenarios include trying to index documents into non-existent indices, attempting to update documents that don't exist, permission issues with the target index, or malformed document data that Elasticsearch cannot parse.

Typical symptoms

  • Bulk API requests return with "errors": true in the response
  • Individual operations in the bulk response show "status": 400 or other error codes
  • Logs show "failed to execute bulk item" messages with specific error details
  • Only some documents from a bulk request are successfully indexed
  • Application receives partial success with some failed operations mixed in

Common causes

  1. Attempting to index documents into a non-existent index without auto-create permissions
  2. Trying to update or delete documents that do not exist in the index
  3. Insufficient permissions for the target index or data stream
  4. Document data contains malformed JSON or invalid field types
  5. Exceeding the 100MB HTTP request size limit for bulk operations
  6. Version conflicts when updating documents with outdated version numbers
  7. Mapping conflicts where document fields don't match the index mapping

How to fix "BulkItemResponse: failed to execute bulk item (index)"

1Check the bulk response for detailed error information

When you receive a bulk response with errors, examine each failed item's error object. Use the filter_path=items.*.error query parameter to simplify the response:

json
// Example bulk request
POST /_bulk?filter_path=items.*.error
{ "index": { "_index": "my-index", "_id": "1" } }
{ "title": "Test document" }
{ "index": { "_index": "my-index", "_id": "2" } }
{ "title": "Another document" }

// Response showing only errors
{
  "items": [
    {
      "index": {
        "error": {
          "type": "document_missing_exception",
          "reason": "[_doc][1]: document missing",
          "index_uuid": "abc123",
          "shard": "0",
          "index": "my-index"
        }
      }
    }
  ]
}

Look for the type and reason fields in each error object to understand what went wrong.

2Verify index existence and permissions

Check if the target index exists and your user has proper permissions:

bash
# Check if index exists
curl -X GET "localhost:9200/my-index" -u "username:password"

# Check index settings and mappings
curl -X GET "localhost:9200/my-index/_settings" -u "username:password"
curl -X GET "localhost:9200/my-index/_mapping" -u "username:password"

# Create the index if it doesn't exist (with auto-create enabled)
curl -X PUT "localhost:9200/my-index" -u "username:password" -H 'Content-Type: application/json' -d'
{
  "settings": {
    "number_of_shards": 1,
    "number_of_replicas": 1
  }
}
'

Ensure your Elasticsearch user has the necessary privileges:
- indices:data/write/index for index operations
- indices:data/write/bulk for bulk operations
- indices:admin/create if auto-creating indices

3Validate document structure and data types

Ensure your documents match the index mapping. Common issues include:

1. Type mismatches: Trying to index a string into a numeric field
2. Missing required fields: If the mapping requires certain fields
3. Invalid JSON: Malformed JSON in the document source

json
// Bad: String in numeric field
{
  "price": "not-a-number"  // Error if price is mapped as float
}

// Good: Correct type
{
  "price": 29.99
}

// Bad: Missing required field
{
  "name": "Product"
  // Error if "category" is required
}

// Good: Includes required field
{
  "name": "Product",
  "category": "electronics"
}

Use the Validate API to test documents before bulk indexing:

bash
curl -X GET "localhost:9200/my-index/_validate/query?explain" -u "username:password" -H 'Content-Type: application/json' -d'
{
  "query": {
    "bool": {
      "must": [
        { "match": { "title": "test" } }
      ]
    }
  }
}
'
4Handle version conflicts and document existence

For update and delete operations, ensure documents exist and handle version conflicts:

json
// Update operation - document must exist
{ "update": { "_index": "my-index", "_id": "1" } }
{ "doc": { "status": "updated" } }

// Delete operation - document must exist
{ "delete": { "_index": "my-index", "_id": "1" } }

// Create operation - document must NOT exist (or use op_type=index)
{ "create": { "_index": "my-index", "_id": "1" } }
{ "title": "New document" }

Strategies to handle these cases:

1. Check document existence first: Query for documents before attempting updates/deletes
2. Use upsert pattern: For updates, provide a document to create if it doesn't exist
3. Handle version conflicts: Use retry_on_conflict parameter or implement retry logic

json
// Update with upsert
{ "update": { "_index": "my-index", "_id": "1", "retry_on_conflict": 3 } }
{
  "doc": { "status": "updated" },
  "doc_as_upsert": true  // Creates document if it doesn't exist
}
5Optimize bulk request size and implement error handling

Break large bulk requests into smaller batches and implement proper error handling:

javascript
// Example: Process bulk requests with error handling
async function processBulkWithRetry(documents, batchSize = 1000) {
  const batches = [];
  for (let i = 0; i < documents.length; i += batchSize) {
    batches.push(documents.slice(i, i + batchSize));
  }

  const results = [];
  for (const batch of batches) {
    let retryCount = 0;
    let success = false;

    while (!success && retryCount < 3) {
      try {
        const response = await elasticsearchClient.bulk({
          body: batch.flatMap(doc => [
            { index: { _index: 'my-index', _id: doc.id } },
            doc
          ])
        });

        if (response.errors) {
          // Handle individual failed items
          const failedItems = response.items.filter(item => item.index.error);
          console.log('Failed items: ' + failedItems.length);

          // Optionally retry failed items individually
          for (const item of failedItems) {
            // Implement individual retry logic
          }
        }

        results.push(response);
        success = true;
      } catch (error) {
        retryCount++;
        if (retryCount === 3) {
          throw new Error('Failed after 3 retries: ' + error.message);
        }
        await new Promise(resolve => setTimeout(resolve, 1000 * retryCount));
      }
    }
  }

  return results;
}

Key optimizations:
- Keep batch sizes under 5-10MB for optimal performance
- Monitor bulk queue size and adjust concurrency
- Implement exponential backoff for retries
- Log detailed error information for debugging

Advanced notes

## Advanced Troubleshooting

### Data Stream Considerations
When working with data streams, only create operations are allowed in bulk requests. Attempting to use index, update, or delete operations on data streams will fail. Data streams are append-only and designed for time-series data.

### Mapping Dynamic Templates
If you're experiencing mapping conflicts, consider using dynamic templates to control how new fields are mapped:

json
PUT /my-index
{
  "mappings": {
    "dynamic_templates": [
      {
        "strings_as_keywords": {
          "match_mapping_type": "string",
          "mapping": {
            "type": "keyword"
          }
        }
      }
    ]
  }
}

### Bulk Processor vs Manual Bulk
Consider using Elasticsearch's Bulk Processor (available in official clients) which handles:
- Automatic flushing based on document count or size
- Concurrent requests with configurable concurrency
- Built-in retry mechanisms
- Error callback handling

### Performance Monitoring
Monitor these metrics when experiencing bulk errors:
- indices.indexing.index_total and indices.indexing.index_failed
- thread_pool.bulk.queue and thread_pool.bulk.rejected
- JVM heap usage and GC pauses
- Network latency between client and cluster

### Security Considerations
- Use API keys with minimal required privileges
- Implement request rate limiting
- Enable audit logging for security investigations
- Consider using ingest pipelines for data transformation before indexing

Frequently asked questions

What does "BulkItemResponse: failed to execute bulk item (index)" mean?
The "BulkItemResponse: failed to execute bulk item (index)" error indicates that one or more indexing operations within a bulk request failed to execute successfully. Elasticsearch's bulk API processes multiple operations in a single HTTP request for efficiency, but each operation is executed independently. When an individual operation fails (like an index action), the overall bulk request may still partially succeed, but the response will include detailed error information for each failed item.
How do I fix "BulkItemResponse: failed to execute bulk item (index)"?
This error occurs when Elasticsearch fails to process one or more operations in a bulk request. The bulk API allows multiple index, create, update, and delete operations in a single request, but individual items can fail due to document conflicts, missing indices, permission issues, or malformed data.
What causes "BulkItemResponse: failed to execute bulk item (index)"?
Attempting to index documents into a non-existent index without auto-create permissions Trying to update or delete documents that do not exist in the index Insufficient permissions for the target index or data stream
Is the "BulkItemResponse: failed to execute bulk item (index)" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading