The error could not find or load main class org.gradle.wrapper.GradleWrapperMain almost always means the gradle-wrapper.jar file is missing or unreadable in your project checkout, so the wrapper script has no code to launch. The gradlew script is just a thin launcher; the actual bootstrapping logic lives in that JAR under gradle/wrapper/. When the JAR is gone, the JVM cannot find the main class it was told to run, and the build dies before Gradle ever starts.
This is one of the most common "works on my machine, breaks in CI" failures in the Java ecosystem, and the fix is straightforward once you understand what the wrapper is actually made of.
What the Gradle wrapper is made of
Running ./gradlew build does not run Gradle directly. It runs a small set of committed files that download and launch the correct Gradle version:
gradlewandgradlew.bat— the shell and batch launcher scripts.gradle/wrapper/gradle-wrapper.properties— declares which Gradle distribution to fetch.gradle/wrapper/gradle-wrapper.jar— the code that reads the properties file and does the download-and-launch work.
The gradlew script invokes the JVM with org.gradle.wrapper.GradleWrapperMain as the entry point, and that class lives inside gradle-wrapper.jar. Remove the JAR and the launcher points at a class that no longer exists. Hence the error.
The number-one cause: a gitignored JAR
The most frequent reason the JAR goes missing is a .gitignore rule that excludes *.jar. A well-meaning rule meant to keep build artifacts out of version control also silently drops gradle-wrapper.jar, which is one of the few JARs you are supposed to commit.
Check whether Git is ignoring it:
git check-ignore -v gradle/wrapper/gradle-wrapper.jar
If that prints a matching rule, that is your culprit. Force-add the file and exclude it from the ignore rule:
git add -f gradle/wrapper/gradle-wrapper.jar
Then add a negation to .gitignore so it stays tracked:
*.jar
!gradle/wrapper/gradle-wrapper.jar
Commit, and the next fresh clone (including your CI runner) will have the file.
Regenerating the wrapper if the JAR is truly gone
If the JAR was never committed and you have no copy, regenerate the wrapper from an installed Gradle:
gradle wrapper --gradle-version 8.7
That command recreates all four wrapper files with a matching, consistent set. If you do not have a system Gradle installed, copy gradle-wrapper.jar and gradle-wrapper.properties from another project on the same Gradle version, then run the wrapper task once things are working to normalize them.
Do not download a gradle-wrapper.jar from a random forum or gist. Which brings us to the part that matters for security.
The Maven equivalent, and why it is the same problem
Maven has an identical failure. If you see could not find or load main class org.apache.maven.wrapper.mavenwrappermain, the cause is the same shape: .mvn/wrapper/maven-wrapper.jar is missing from the checkout. The fix mirrors Gradle's, either force-adding the committed JAR or regenerating with mvn wrapper:wrapper. Both wrappers commit a small JAR that bootstraps the real build tool, and both break the same way when that JAR is filtered out of version control.
Verify the JAR before you trust it
Here is where a build annoyance turns into a supply-chain concern. The wrapper JAR runs with the full privileges of your build, and your build often holds credentials, signing keys, and deployment access. A tampered gradle-wrapper.jar is a known attack technique: swap the JAR, and arbitrary code runs on every developer machine and CI runner that executes ./gradlew.
Two controls address this:
The Gradle wrapper properties file supports a distributionSha256Sum entry that pins the checksum of the Gradle distribution it downloads. Set it so a swapped distribution fails loudly instead of running silently.
Validate the wrapper JAR itself in CI. There is an official GitHub Action, gradle/wrapper-validation-action, that checks the committed gradle-wrapper.jar against a list of known-good hashes for every official Gradle release. Add it as the first step of your pipeline so an unexpected JAR blocks the build.
Beyond the wrapper, the same integrity mindset applies to everything the build pulls in. Pinned versions, checksums, and a scan of the resolved dependency tree are what keep a compromised artifact from riding into production. An SCA tool such as Safeguard can flag known-bad components in that tree, which is one slice of what our SCA product does. If you want the fuller picture on build-integrity practices, the academy covers it.
Quick checklist
- Confirm
gradle/wrapper/gradle-wrapper.jarexists in a fresh clone. - If
.gitignoreexcludes*.jar, add a negation for the wrapper JAR and force-add it. - Regenerate with
gradle wrapper --gradle-version <version>if the JAR is unrecoverable. - Pin
distributionSha256Sumingradle-wrapper.properties. - Run wrapper validation in CI so a tampered JAR fails the build.
FAQ
Why do I get "could not find or load main class org.gradle.wrapper.GradleWrapperMain"?
Because gradle-wrapper.jar is missing or unreadable in your checkout. The gradlew launcher tries to run the GradleWrapperMain class, which lives inside that JAR, and fails when the JAR is absent. The usual cause is a .gitignore rule excluding all *.jar files.
How do I fix the missing gradle-wrapper.jar?
Force-add the committed JAR with git add -f gradle/wrapper/gradle-wrapper.jar and add a negation rule to .gitignore, or regenerate the wrapper with gradle wrapper --gradle-version <version> if you have Gradle installed locally.
What about "could not find or load main class org.apache.maven.wrapper.mavenwrappermain"?
Same problem, Maven edition. The .mvn/wrapper/maven-wrapper.jar is missing from your checkout. Force-add the committed JAR or regenerate it with mvn wrapper:wrapper.
Is it safe to download gradle-wrapper.jar from the internet?
No. The wrapper JAR executes with your build's full privileges, so a tampered copy can run arbitrary code on every machine that builds the project. Regenerate it from an official Gradle install, pin distributionSha256Sum, and validate the JAR in CI with the official wrapper-validation action.