diff --git a/src/content/docs/paper/dev/getting-started/userdev.md b/src/content/docs/paper/dev/getting-started/userdev.md
index 3746b9a0c..74f6c8063 100644
--- a/src/content/docs/paper/dev/getting-started/userdev.md
+++ b/src/content/docs/paper/dev/getting-started/userdev.md
@@ -86,6 +86,30 @@ You should remove any dependency on the Paper API, as the dev bundle includes th
 
 :::
 
+:::note[Configuring the Java toolchain for userdev setup]
+
+A given dev bundle may not always support the Java toolchain Gradle is configured to use
+(whether configured explicitly or inherited from the Gradle runtime).
+If you are getting an error during the execution of `paperweightUserdevSetup` (especially patch application failures),
+you can try setting paperweight's `javaLauncher` property to a different Java version.
+
+For example, with 1.17.1:
+```kts title="build.gradle.kts"
+paperweight {
+  javaLauncher = javaToolchains.launcherFor {
+    // Example scenario:
+    // Paper 1.17.1 was originally built with JDK 16 and the bundle
+    // has not been updated to work with 21+ (but we want to compile with a 25 toolchain)
+    languageVersion = JavaLanguageVersion.of(17)
+  }
+}
+```
+
+Among others, the [multi-project branch of the PaperMC/paperweight-test-plugin](https://github.com/PaperMC/paperweight-test-plugin/tree/multi-project)
+makes use of this feature.
+
+:::
+
 ## Gradle tasks
 
 ### `reobfJar`