Gradle "Could not find or load main class org.gradle.wrapper.GradleWrapperMain" in CI

By Kaveh Alemi·Latchkey

The gradlew script launches the JVM with the wrapper main class, which lives in gradle/wrapper/gradle-wrapper.jar. When that jar is absent from the checkout, the JVM cannot find the class and the build never starts.

What this error means

A ./gradlew step fails immediately with "Error: Could not find or load main class org.gradle.wrapper.GradleWrapperMain" and a "Caused by: java.lang.ClassNotFoundException".

Error: Could not find or load main class org.gradle.wrapper.GradleWrapperMain
Caused by: java.lang.ClassNotFoundException: org.gradle.wrapper.GradleWrapperMain

Common causes

gradle-wrapper.jar was never committed

A .gitignore rule that ignores *.jar excluded the wrapper jar, so the repository has the scripts but not the jar CI needs.

A sparse or partial checkout skipped the wrapper

A shallow path-filtered checkout did not include gradle/wrapper/, so the jar is missing on the runner even though it exists in the repo.

How to fix it

Commit the wrapper jar

1. Regenerate the wrapper locally so gradle-wrapper.jar is present.
2. Force-add the jar past any .gitignore rule and commit it.
3. Confirm gradle/wrapper/gradle-wrapper.jar is in the repository.

gradle wrapper
git add -f gradle/wrapper/gradle-wrapper.jar

Check the wrapper out in CI

Ensure the checkout includes the wrapper directory and is not path-filtered to exclude it.

- uses: actions/checkout@v4
- run: ./gradlew build

How to prevent it

• Keep gradle/wrapper/gradle-wrapper.jar committed and not gitignored.
• Add a .gitignore exception for the wrapper jar if *.jar is ignored.
• Avoid path-filtered checkouts that drop the wrapper directory.

Frequently asked questions

Related guides

References

• Apache Maven guides
• Gradle user manual
• GitHub Actions documentation