IntelliJ Platform Gradle Plugin: The currently selected Java Runtime is not JetBrains Runtime (JBR)

topics/appendix/tools/intellij_platform_gradle_plugin/tools_intellij_platform_gradle_plugin_faq.md

@@ -172,4 +172,64 @@ tasks {
 }
 ```
 
+### The currently selected Java Runtime is not JetBrains Runtime (JBR)
+
+When running tests or IDE with your plugin loaded, it is necessary to use JetBrains Runtime (JBR).
+In the case, no JBR is found in the plugin configuration, there's the following warning logged by the [`verifyPluginProjectConfiguration`](tools_intellij_platform_gradle_plugin_tasks.md#verifyPluginProjectConfiguration) task:
+
+
+```
+The currently selected Java Runtime is not JetBrains Runtime (JBR).
+This may lead to unexpected IDE behaviors.
+Please use IntelliJ Platform binary release with bundled JBR
+or define it explicitly with project dependencies or JVM Toolchain.
+```
+
+To correctly run your tests or a specific IDE:
+- use a binary IDE distribution with bundled JetBrains Runtime, i.e., by referring to a local IDE [`local(localPath)`](tools_intellij_platform_gradle_plugin_dependencies_extension.md#custom-target-platforms)
+  ```kotlin
+  repositories {
+    mavenCentral()
+
+    intellijPlatform {
+      defaultRepositories()
+    }
+  }
+
+  dependencies {
+    intellijPlatform {
+      local("/Users/hsz/Applications/IntelliJ IDEA Ultimate.app")
+    }
+  }
+  ```
+
+- add an explicit dependency on a JetBrains Runtime with [`jetbrainsRuntime()`](tools_intellij_platform_gradle_plugin_dependencies_extension.md#java-runtime)
+  ```kotlin
+  repositories {
+    mavenCentral()
+
+    intellijPlatform {
+      defaultRepositories()
+      jetbrainsRuntime()
+    }
+  }
+
+  dependencies {
+    intellijPlatform {
+      intellijIdeaCommunity("%ijPlatform%")
+      jetbrainsRuntime(...)
+    }
+  }
+  ```
+- specify the vendor when configuring the JVM Toolchain along with [Foojay Toolchains Plugin](https://github.com/gradle/foojay-toolchains):
+  ```kotlin
+  kotlin {
+    jvmToolchain {
+      languageVersion = JavaLanguageVersion.of(17)
+      vendor = JvmVendorSpec.JETBRAINS
+    }
+  }
+  ```
+
+
 <include from="snippets.md" element-id="missingContent"/>

topics/appendix/tools/intellij_platform_gradle_plugin/tools_intellij_platform_gradle_plugin_tasks.md

@@ -1325,6 +1325,7 @@ Validates the plugin project configuration:
 - The Kotlin plugin in version `1.8.20` is not used with IntelliJ Platform Gradle Plugin due to the 'java.lang.OutOfMemoryError: Java heap space' exception.
 - The Kotlin Coroutines library should not be added explicitly to the project as it is already provided with the IntelliJ Platform.
 - The IntelliJ Platform cache directory should be excluded from the version control system. Add the `.intellijPlatform`'` entry to the <path>.gitignore</path> file.
+- The currently selected Java Runtime is not JetBrains Runtime (JBR).
 
 For more details regarding the Java version used in the specific IntelliJ SDK, see [](build_number_ranges.md).