diff --git a/subprojects/docs/src/docs/userguide/kotlin_dsl.adoc b/subprojects/docs/src/docs/userguide/kotlin_dsl.adoc
index 4ae3819b6c9a..85ca3c3203bd 100644
--- a/subprojects/docs/src/docs/userguide/kotlin_dsl.adoc
+++ b/subprojects/docs/src/docs/userguide/kotlin_dsl.adoc
@@ -716,6 +716,12 @@ All three libraries and their dependencies are bundled with Gradle, so these dep
  * Configures the Kotlin compiler with the same settings that are used for Kotlin DSL scripts, ensuring consistency between your build logic and those scripts.
  * Enables support for <<kotdsl:precompiled_plugins,precompiled script plugins>>.
 
+[CAUTION]
+.Avoid specifying a version for the `kotlin-dsl` plugin
+====
+Each Gradle release is meant to be used with a specific version of the `kotlin-dsl` plugin and compatibility between arbitrary Gradle releases and `kotlin-dsl` plugin versions is not guaranteed. Using an unexpected version of the `kotlin-dsl` plugin in a build will emit a warning and can cause hard to diagnose problems.
+====
+
 This is the basic configuration you need to use the plugin:
 
 .Applying the Kotlin DSL Plugin to a `buildSrc` project