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

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

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.

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.