From 9218cac655e0438e1d08fb1037a9a7bb6f8c2b7d Mon Sep 17 00:00:00 2001
From: Tiffany Hrabusa <30397949+tiffany76@users.noreply.github.com>
Date: Sat, 22 Jun 2024 15:03:23 -0700
Subject: [PATCH] Add section on null maps to troubleshooting page (#4731)

---
 content/en/docs/collector/troubleshooting.md | 20 +++++++++++++++++++-
 1 file changed, 19 insertions(+), 1 deletion(-)

diff --git a/content/en/docs/collector/troubleshooting.md b/content/en/docs/collector/troubleshooting.md
index e48030b648fb..2483bddb0058 100644
--- a/content/en/docs/collector/troubleshooting.md
+++ b/content/en/docs/collector/troubleshooting.md
@@ -2,7 +2,7 @@
 title: Troubleshooting
 description: Recommendations for troubleshooting the Collector
 weight: 25
-cSpell:ignore: pprof tracez zpages
+cSpell:ignore: confmap pprof tracez zpages
 ---
 
 On this page, you can learn how to troubleshoot the health and performance of
@@ -359,3 +359,21 @@ container, producing the error message
 the `NO_WINDOWS_SERVICE=1` environment variable must be set to force the
 Collector to start as if it were running in an interactive terminal, without
 attempting to run as a Windows service.
+
+### Collector is experiencing configuration issues
+
+The Collector might experience problems due to configuration issues.
+
+#### Null maps
+
+During configuration resolution of multiple configs, values in earlier configs
+are removed in favor of later configs, even if the later value is null. You can
+fix this issue by
+
+- Using `{}` to represent an empty map, such as `processors: {}` instead of
+  `processors:`.
+- Omitting empty configurations such as `processors:` from the configuration.
+
+See
+[confmap troubleshooting](https://github.com/open-telemetry/opentelemetry-collector/blob/main/confmap/README.md#null-maps)
+for more information.