diff --git a/doc/user/application_security/sast/customize_rulesets.md b/doc/user/application_security/sast/customize_rulesets.md
index d293823adddc13db5adb495c1e2063af052eed38..fd10bf3b3c0b73ed47f70b46cea263703d00f340 100644
--- a/doc/user/application_security/sast/customize_rulesets.md
+++ b/doc/user/application_security/sast/customize_rulesets.md
@@ -115,6 +115,16 @@ variables:
 
 See [specify a private remote configuration example](#specify-a-private-remote-configuration) for advanced usage.
 
+### Troubleshooting remote configuration files
+
+If remote configuration file doesn't seem to be applying customizations correctly, the causes can be:
+
+1. Your repository has a local `.gitlab/sast-ruleset.toml` file.
+    - A local file is used if it's present, even if a remote configuration is set as a variable.
+    - A change to this logic is considered in [issue 414732](https://gitlab.com/gitlab-org/gitlab/-/issues/414732).
+1. There is a problem with authentication.
+    - To check whether this is the cause of the problem, try referencing a configuration file from a repository location that doesn't require authentication.
+
 ## Schema
 
 ### The top-level section
diff --git a/doc/user/application_security/secret_detection/index.md b/doc/user/application_security/secret_detection/index.md
index 7cefb6e1ce8138d536e22986125a275360622488..32616619a145d5dcbb36670becae2e23388838a8 100644
--- a/doc/user/application_security/secret_detection/index.md
+++ b/doc/user/application_security/secret_detection/index.md
@@ -520,7 +520,7 @@ variables:
   SECRET_DETECTION_RULESET_GIT_REFERENCE: "gitlab.com/example-group/example-ruleset-project"
 ```
 
-For more information on the syntax of remote configurations, see the
+For more information on the syntax of remote configurations and how to troubleshoot, see the
 [specify a private remote configuration example](../sast/customize_rulesets.md#specify-a-private-remote-configuration)
 on the SAST customize rulesets page.