Gradle ":compileJava" Fails: "cannot find symbol" - Fix in CI

By Daniel Zoghalchali·Latchkey

javac could not resolve a referenced symbol while Gradle compiled your code. The class is not on the compile classpath, a generated source was not produced, or the reference is stale.

What this error means

The :compileJava task fails with error: cannot find symbol, pointing at a class, method, or variable. The build stops at compilation; nothing downstream runs.

gradle output

> Task :app:compileJava FAILED
src/main/java/com/example/App.java:12: error: cannot find symbol
    import com.acme.util.Helper;
                        ^
  symbol:   class Helper
  location: package com.acme.util

Diagnose it: get the real failure out of Gradle

Gradle summarises failures aggressively, and the top-level message frequently describes a downstream symptom rather than the cause. Re-run the failing task with diagnostics before changing build logic.

Terminal

# the actual stack, plus what Gradle decided about the build
./gradlew <task> --stacktrace --info

# is a stale daemon or cache involved?
./gradlew --stop
./gradlew <task> --no-daemon --no-build-cache

# what does Gradle think the environment is?
./gradlew -version

Common causes

Dependency missing from the compile classpath

A library is declared runtimeOnly/testImplementation (or not at all) when the code needs it at compile time, so the symbol is not visible to javac.

Generated source not produced

Code generated by an annotation processor or a codegen task (e.g. MapStruct, generated DTOs) was not produced, so the referenced class does not exist yet.

How to fix it

Add the dependency to the right configuration

Declare the library as implementation (or api) so it is on the compile classpath.

build.gradle.kts

dependencies {
    implementation("com.acme:util:1.4.0")
    annotationProcessor("org.mapstruct:mapstruct-processor:1.6.0")
}

Verify generation and classpath

Run ./gradlew :app:dependencies --configuration compileClasspath to confirm the library is present.
Ensure annotation processors are declared via annotationProcessor(...), not just implementation(...).
Clean stale outputs with ./gradlew clean if generated sources went out of sync.

Configuration cache and CI

The configuration cache rejects build logic that reads mutable state at execution time, which is why enabling it surfaces errors an existing build never showed.
Run with --configuration-cache-problems=warn first to see the full list rather than failing on the first one.
A cached configuration keyed to a different environment is worse than none. Include the JDK version in your cache key.

How to prevent it

Declare compile-time dependencies as implementation/api, wire annotation processors via annotationProcessor, and keep generated-source tasks in the compile graph.

Frequently asked questions

What causes Gradle ":compileJava" Fails: "cannot find symbol"?

There are 2 common causes: dependency missing from the compile classpath and generated source not produced. A library is declared runtimeOnly/testImplementation (or not at all) when the code needs it at compile time, so the symbol is not visible to javac.

How do I fix Gradle ":compileJava" Fails: "cannot find symbol"?

There are 2 fixes depending on which cause you have: add the dependency to the right configuration and verify generation and classpath. Work through them in order, since the first is the most common.

What does Gradle ":compileJava" Fails: "cannot find symbol" actually mean?

The :compileJava task fails with error: cannot find symbol, pointing at a class, method, or variable.

How do I stop Gradle ":compileJava" Fails: "cannot find symbol" happening again?

Declare compile-time dependencies as implementation/api, wire annotation processors via annotationProcessor, and keep generated-source tasks in the compile graph.