Improved error message when index field type is unknown

docs/changelog/122860.yaml

@@ -0,0 +1,5 @@
+pr: 122860
+summary: Improved error message when index field type is invalid
+area: Mapping
+type: enhancement
+issues: []

rest-api-spec/src/yamlRestTest/resources/rest-api-spec/test/indices.create/10_basic.yml

@@ -214,3 +214,62 @@
             index.mode: lookup
             index.number_of_shards: 2
 
+---
+"Create index with invalid field type":
+  - requires:
+      cluster_features: [ "mapper.unknown_field_mapping_update_error_message" ]
+      reason: "Update error message for unknown field type"
+
+  - do:
+      catch: /bad_request/
+      indices.create:
+        index: test_index
+        body:
+          mappings:
+            properties:
+              content:
+                type: invalid
+
+  - match: { error.type: "mapper_parsing_exception" }
+  - match: { error.reason: "The mapper type [invalid] declared on field [content] does not exist. It might have been created within a future version or requires a plugin to be installed. Check the documentation." }
+
+---
+"Create index with invalid runtime field type":
+  - requires:
+      cluster_features: [ "mapper.unknown_field_mapping_update_error_message" ]
+      reason: "Update error message for unknown field type"
+
+  - do:
+      catch: /bad_request/
+      indices.create:
+        index: test_index
+        body:
+          mappings:
+            runtime:
+              content:
+                type: invalid
+
+  - match: { error.type: "mapper_parsing_exception" }
+  - match: { error.reason: "The mapper type [invalid] declared on field [content] does not exist. It might have been created within a future version or requires a plugin to be installed. Check the documentation." }
+
+---
+"Create index with invalid multi-field type":
+  - requires:
+      cluster_features: [ "mapper.unknown_field_mapping_update_error_message" ]
+      reason: "Update error message for unknown field type"
+
+  - do:
+      catch: /bad_request/
+      indices.create:
+        index: test_index
+        body:
+          mappings:
+            properties:
+              city:
+                type: text
+                fields:
+                  raw:
+                    type: invalid
+
+  - match: { error.type: "mapper_parsing_exception" }
+  - match: { error.reason: "The mapper type [invalid] declared on field [city] does not exist. It might have been created within a future version or requires a plugin to be installed. Check the documentation." }

server/src/main/java/org/elasticsearch/index/mapper/MapperFeatures.java

@@ -54,6 +54,7 @@ public Set<NodeFeature> getTestFeatures() {
             TSDB_NESTED_FIELD_SUPPORT,
             SourceFieldMapper.SYNTHETIC_RECOVERY_SOURCE,
             ObjectMapper.SUBOBJECTS_FALSE_MAPPING_UPDATE_FIX,
+            ObjectMapper.UKNOWN_FIELD_MAPPING_UPDATE_ERROR_MESSAGE,
             DOC_VALUES_SKIPPER
         );
     }

server/src/main/java/org/elasticsearch/index/mapper/ObjectMapper.java

@@ -50,6 +50,9 @@ public class ObjectMapper extends Mapper {
     private static final DeprecationLogger deprecationLogger = DeprecationLogger.getLogger(ObjectMapper.class);
     public static final FeatureFlag SUB_OBJECTS_AUTO_FEATURE_FLAG = new FeatureFlag("sub_objects_auto");
     static final NodeFeature SUBOBJECTS_FALSE_MAPPING_UPDATE_FIX = new NodeFeature("mapper.subobjects_false_mapping_update_fix");
+    static final NodeFeature UKNOWN_FIELD_MAPPING_UPDATE_ERROR_MESSAGE = new NodeFeature(
+        "mapper.unknown_field_mapping_update_error_message"
+    );
 
     public static final String CONTENT_TYPE = "object";
     static final String STORE_ARRAY_SOURCE_PARAM = "store_array_source";
@@ -396,7 +399,15 @@ protected static void parseProperties(Builder objBuilder, Map<String, Object> pr
                     }
                     Mapper.TypeParser typeParser = parserContext.typeParser(type);
                     if (typeParser == null) {
-                        throw new MapperParsingException("No handler for type [" + type + "] declared on field [" + fieldName + "]");
+                        throw new MapperParsingException(
+                            "The mapper type ["
+                                + type
+                                + "] declared on field ["
+                                + fieldName
+                                + "] does not exist."
+                                + " It might have been created within a future version or requires a plugin to be installed."
+                                + " Check the documentation."
+                        );
                     }
                     Mapper.Builder fieldBuilder;
                     if (objBuilder.subobjects.isPresent() && objBuilder.subobjects.get() != Subobjects.ENABLED) {

server/src/main/java/org/elasticsearch/index/mapper/RuntimeField.java

@@ -179,7 +179,15 @@ static Map<String, RuntimeField> parseRuntimeFields(
                 }
                 Parser typeParser = parserContext.runtimeFieldParser(type);
                 if (typeParser == null) {
-                    throw new MapperParsingException("No handler for type [" + type + "] declared on runtime field [" + fieldName + "]");
+                    throw new MapperParsingException(
+                        "The mapper type ["
+                            + type
+                            + "] declared on field ["
+                            + fieldName
+                            + "] does not exist."
+                            + " It might have been created within a future version or requires a plugin to be installed."
+                            + " Check the documentation."
+                    );
                 }
                 runtimeFields.put(fieldName, builder.apply(typeParser.parse(fieldName, propNode, parserContext)));
                 propNode.remove("type");

server/src/main/java/org/elasticsearch/index/mapper/TypeParsers.java

@@ -161,7 +161,15 @@ public static boolean parseMultiField(
 
                 Mapper.TypeParser typeParser = parserContext.typeParser(type);
                 if (typeParser == null) {
-                    throw new MapperParsingException("no handler for type [" + type + "] declared on field [" + multiFieldName + "]");
+                    throw new MapperParsingException(
+                        "The mapper type ["
+                            + type
+                            + "] declared on field ["
+                            + multiFieldName
+                            + "] does not exist."
+                            + " It might have been created within a future version or requires a plugin to be installed."
+                            + " Check the documentation."
+                    );
                 }
                 if (typeParser instanceof FieldMapper.TypeParser == false) {
                     throw new MapperParsingException("Type [" + type + "] cannot be used in multi field");

server/src/test/java/org/elasticsearch/index/mapper/RootObjectMapperTests.java

@@ -313,13 +313,21 @@ public void testRuntimeSectionMerge() throws IOException {
     public void testRuntimeSectionNonRuntimeType() throws IOException {
         XContentBuilder mapping = runtimeFieldMapping(builder -> builder.field("type", "unknown"));
         MapperParsingException e = expectThrows(MapperParsingException.class, () -> createMapperService(mapping));
-        assertEquals("Failed to parse mapping: No handler for type [unknown] declared on runtime field [field]", e.getMessage());
+        assertEquals(
+            "Failed to parse mapping: The mapper type [unknown] declared on field [field] does not exist."
+                + " It might have been created within a future version or requires a plugin to be installed. Check the documentation.",
+            e.getMessage()
+        );
     }
 
     public void testRuntimeSectionHandlerNotFound() throws IOException {
         XContentBuilder mapping = runtimeFieldMapping(builder -> builder.field("type", "unknown"));
         MapperParsingException e = expectThrows(MapperParsingException.class, () -> createMapperService(mapping));
-        assertEquals("Failed to parse mapping: No handler for type [unknown] declared on runtime field [field]", e.getMessage());
+        assertEquals(
+            "Failed to parse mapping: The mapper type [unknown] declared on field [field] does not exist."
+                + " It might have been created within a future version or requires a plugin to be installed. Check the documentation.",
+            e.getMessage()
+        );
     }
 
     public void testRuntimeSectionMissingType() throws IOException {