diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 3d4f61950..5c52f1f78 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -38,13 +38,10 @@ note the required manual actions for IntelliJ.
 
 ### Gradle & JDK 17
 
-Given that the project currently uses JDK 17 features, it requires to run Gradle itself with JDK 17, which in turn requires the below settings in `~/.gradle/gradle.properties`.
-Without those settings you might see issues when running `./gradlew spotlessApply`.
+Run Gradle with a **JDK 17** daemon.
 
-```
-org.gradle.jvmargs=--add-exports jdk.compiler/com.sun.tools.javac.api=ALL-UNNAMED \
-  --add-exports jdk.compiler/com.sun.tools.javac.file=ALL-UNNAMED \
-  --add-exports jdk.compiler/com.sun.tools.javac.parser=ALL-UNNAMED \
-  --add-exports jdk.compiler/com.sun.tools.javac.tree=ALL-UNNAMED \
-  --add-exports jdk.compiler/com.sun.tools.javac.util=ALL-UNNAMED
-```
+The compile and test tasks pin themselves to a Java 17 toolchain, so those run correctly
+regardless of which JDK launches Gradle, as long as a JDK 17 is installed and discoverable.
+Spotless is the exception: the `google-java-format` version it uses only runs on JDK 17 and
+fails with `NoSuchMethodError` / `NoClassDefFoundError` when the Gradle daemon runs on a newer
+JDK, so `./gradlew spotlessApply` (and `spotlessCheck`) require the daemon itself to be on JDK 17.
diff --git a/readme.md b/readme.md
index bfe9ffd6b..1741f0e75 100644
--- a/readme.md
+++ b/readme.md
@@ -7,6 +7,8 @@ Substrait Java is a project that makes it easier to build [Substrait](https://su
 The supported features are formally specified in the Substrait dialect file [spark_dialect.yaml](spark/spark_dialect.yaml).
 
 ## Building
+Building requires a **JDK 17** installation, and Gradle itself must run on JDK 17 (see [Gradle & JDK 17](CONTRIBUTING.md#gradle--jdk-17) in the contributing guide for details).
+
 After you've cloned the project through git, Substrait Java is built with a tool called [Gradle](https://gradle.org/). To build, execute the following:
 ```
 ./gradlew build