diff --git a/crates/rust-analyzer/src/config.rs b/crates/rust-analyzer/src/config.rs
index 3671367025..4417c8d13d 100644
--- a/crates/rust-analyzer/src/config.rs
+++ b/crates/rust-analyzer/src/config.rs
@@ -180,7 +180,8 @@ config_data! {
         runnables_cargoExtraArgs: Vec<String>   = "[]",
 
         /// Path to the rust compiler sources, for usage in rustc_private projects, or "discover"
-        /// to try to automatically find it.
+        /// to try to automatically find it. Any project which uses rust-analyzer with the rustcPrivate
+        /// crates must set `[package.metadata.rust-analyzer] rustc_private=true` to use it.
         rustcSource : Option<String> = "null",
 
         /// Additional arguments to `rustfmt`.
diff --git a/docs/user/generated_config.adoc b/docs/user/generated_config.adoc
index 1dbf2a611d..504133070b 100644
--- a/docs/user/generated_config.adoc
+++ b/docs/user/generated_config.adoc
@@ -105,7 +105,7 @@
 [[rust-analyzer.runnables.cargoExtraArgs]]rust-analyzer.runnables.cargoExtraArgs (default: `[]`)::
  Additional arguments to be passed to cargo for runnables such as  tests or binaries.\nFor example, it may be `--release`.
 [[rust-analyzer.rustcSource]]rust-analyzer.rustcSource (default: `null`)::
- Path to the rust compiler sources, for usage in rustc_private projects, or "discover"  to try to automatically find it.
+ Path to the rust compiler sources, for usage in rustc_private projects, or "discover"  to try to automatically find it. Any project which uses rust-analyzer with the rustcPrivate  crates must set `[package.metadata.rust-analyzer] rustc_private=true` to use it.
 [[rust-analyzer.rustfmt.extraArgs]]rust-analyzer.rustfmt.extraArgs (default: `[]`)::
  Additional arguments to `rustfmt`.
 [[rust-analyzer.rustfmt.overrideCommand]]rust-analyzer.rustfmt.overrideCommand (default: `null`)::
diff --git a/editors/code/package.json b/editors/code/package.json
index 1987364bc0..b39e8fbe39 100644
--- a/editors/code/package.json
+++ b/editors/code/package.json
@@ -707,7 +707,7 @@
                     }
                 },
                 "rust-analyzer.rustcSource": {
-                    "markdownDescription": "Path to the rust compiler sources, for usage in rustc_private projects, or \"discover\" to try to automatically find it.",
+                    "markdownDescription": "Path to the rust compiler sources, for usage in rustc_private projects, or \"discover\" to try to automatically find it. Any project which uses rust-analyzer with the rustcPrivate crates must set `[package.metadata.rust-analyzer] rustc_private=true` to use it.",
                     "default": null,
                     "type": [
                         "null",