gradle wrapper: Usage & Common CI Errors
Pin the exact Gradle version your build (and CI) uses.
wrapper is the built-in Gradle task that generates or updates the Gradle Wrapper: the gradlew / gradlew.bat scripts and gradle/wrapper/gradle-wrapper.properties. The wrapper pins a specific Gradle version so every machine and CI runner builds with the same one.
What it does
wrapper writes the wrapper scripts and a properties file recording the Gradle distribution URL and version. Committing these lets ./gradlew download and use the pinned version automatically, removing "works on my machine" version drift.
Common usage
gradle wrapper --gradle-version 8.7
./gradlew wrapper --gradle-version 8.7 --distribution-type all
./gradlew --version # confirm the active versionCommon error in CI (and the fix)
Symptom: "Could not find or load main class org.gradle.wrapper.GradleWrapperMain" in CI. Cause: gradle/wrapper/gradle-wrapper.jar is missing (often gitignored or stripped). Fix: commit gradle/wrapper/gradle-wrapper.jar (and gradle-wrapper.properties) to the repo so ./gradlew can bootstrap; regenerate them with gradle wrapper if they were lost.