From ad564240b127480bab33661038c17817982bb676 Mon Sep 17 00:00:00 2001
From: Boaz Leskes <b.leskes@gmail.com>
Date: Wed, 9 May 2018 14:19:50 +0200
Subject: [PATCH] add a comment explaining the need for RetryOnReplicaException
 on missing mappings

---
 .../action/bulk/TransportShardBulkAction.java             | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/server/src/main/java/org/elasticsearch/action/bulk/TransportShardBulkAction.java b/server/src/main/java/org/elasticsearch/action/bulk/TransportShardBulkAction.java
index 57ecb250f7c..7201b878f98 100644
--- a/server/src/main/java/org/elasticsearch/action/bulk/TransportShardBulkAction.java
+++ b/server/src/main/java/org/elasticsearch/action/bulk/TransportShardBulkAction.java
@@ -543,6 +543,14 @@ public class TransportShardBulkAction extends TransportWriteAction<BulkShardRequ
                     + docWriteRequest.opType().getLowercase());
         }
         if (result.getResultType() == Engine.Result.Type.MAPPING_UPDATE_REQUIRED) {
+            // Even though the primary waits on all nodes to ack the mapping changes to the master
+            // (see MappingUpdatedAction.updateMappingOnMaster) we still need to protect against missing mappings
+            // and wait for them. The reason is concurrent requests. Request r1 which has new field f triggers a
+            // mapping update. Assume that that update is first applied on the primary, and only later on the replica
+            // (it’s happening concurrently). Request r2, which now arrives on the primary and which also has the new
+            // field f might see the updated mapping (on the primary), and will therefore proceed to be replicated
+            // to the replica. When it arrives on the replica, there’s no guarantee that the replica has already
+            // applied the new mapping, so there is no other option than to wait.
             throw new TransportReplicationAction.RetryOnReplicaException(replica.shardId(),
                 "Mappings are not available on the replica yet, triggered update: " + result.getRequiredMappingUpdate());
         }