diff --git a/docs/reference/troubleshooting.asciidoc b/docs/reference/troubleshooting.asciidoc
index 75cd0c1be49fc..cf617ed25d099 100644
--- a/docs/reference/troubleshooting.asciidoc
+++ b/docs/reference/troubleshooting.asciidoc
@@ -25,6 +25,7 @@ If you're using Elastic Cloud Hosted, then you can use AutoOps to monitor your c
 * <<allow-all-cluster-allocation,Allow Elasticsearch to allocate the data in the system>>
 * <<allow-all-index-allocation,Allow Elasticsearch to allocate the index>>
 * <<troubleshoot-migrate-to-tiers,Indices mix index allocation filters with data tiers node roles to move through data tiers>>
+* <<troubleshoot-migrate-source-mode,Configuring source mode in mappings is deprecated and replaced by an index setting>>
 * <<increase-tier-capacity,Not enough nodes to allocate all shard replicas>>
 * <<increase-shard-limit,Total number of shards for an index on a single node exceeded>>
 * <<increase-cluster-shard-limit,Total number of shards per node has been reached>>
diff --git a/docs/reference/troubleshooting/data/source-mode-setting.asciidoc b/docs/reference/troubleshooting/data/source-mode-setting.asciidoc
new file mode 100644
index 0000000000000..79c2d8d064d1c
--- /dev/null
+++ b/docs/reference/troubleshooting/data/source-mode-setting.asciidoc
@@ -0,0 +1,49 @@
+[[troubleshoot-migrate-source-mode]]
+== Configuring source mode in mappings is deprecated and replaced by an index setting
+
+Index <<mapping-source-field,source>> mode was previously configured in mappings as follows:
+
+[source,js]
+----
+"mappings": {
+    "source": {
+        "mode": "synthetic"
+    },
+    "foo": {
+        "type": "keyword"
+    },
+    "bar": {
+        "type": "keyword"
+    }
+}
+----
+// NOTCONSOLE
+
+Starting with version 8.18, this method for configuring the source mode is considered
+deprecated and replaced by index setting `index.mapping.source.mode` that accepts the
+same values: `stored` (default), `synthetic` and `disabled`. The index setting can be
+used as follows:
+
+[source,js]
+----
+"settings": {
+    "index.mapping.source.mode": "synthetic"
+}
+"mappings": {
+    "foo": {
+        "type": "keyword"
+    },
+    "bar": {
+        "type": "keyword"
+    }
+}
+----
+// NOTCONSOLE
+
+Existing indexes using the deprecated method for configuring the source mode are not
+affected, but creating new indexes raises warnings and will not be supported in a future
+release. This can be an issue for data streams and other indexes that get regularly
+generated using component templates. To avoid these problems, identify all affected
+component templates, as shown in the <<migration-api-deprecation,deprecation info API>>,
+and update them to use setting `index.mapping.source.mode` instead of
+`mappings.source.mode`, according to the examples above.