Skip to content
javahacks.dev
Java Core

Fix Cannot Find Symbol Java Compile Error Step by Step

Fix the Java cannot find symbol compile error by reading the symbol and location lines, then checking the spelling, import, scope and classpath in that order.

5 min read
Summarize in AI
Flat illustration of a magnifier over lines of a log, with the OpenJDK, Docker, Apache Maven and Gradle logos.

"Cannot find symbol" is the most common compile error in Java, and it has a small number of causes that you can check in a fixed order. The compiler found a name it cannot resolve in that place. It always tells you which name and where, and the two lines beneath the headline are the whole diagnosis. This post gives the checks in order of likelihood, with the example of each, and ends with the causes that look like this error and live elsewhere in the build.

Text
src/main/java/dev/javahacks/OrderService.java:14: error: cannot find symbol
        List<Order> orders = repository.findAll();
        ^
  symbol:   class List
  location: class OrderService

The symbol: line gives the kind of thing (class, variable, method) and its name. The location: line gives where the compiler was looking. Read them literally before guessing. The first example is a missing List, and the others in this post change only those two lines.

1. The name is spelled differently

Java is case sensitive. string, System.out.printIn with the letters i and l swapped, lenght for length and ArrayList<> written Arraylist all produce this error. The symbol: line shows what you typed, and comparing it letter by letter with the declaration finds most typos. An IDE underlines these before you compile, which is a reason to trust the editor's red lines. A related case is a name that exists in your code under a different spelling than in your head, after a rename that touched half the files.

2. The import is missing

java
public class OrderService {
    List<Order> orders;          // error: cannot find symbol, symbol: class List
}

Everything outside java.lang must be imported or written with its full name. Add import java.util.List;. When the symbol is a class from your own project in another package, the import is missing for the same reason. Two classes of the same name in different packages, such as java.util.Date and java.sql.Date, make the IDE offer a choice, and the wrong one compiles and fails later; the compiler error appears only when you call a method that the one you picked does not have.

3. The variable is out of scope

java
for (int i = 0; i < 3; i++) {
    int total = i * 2;
}
System.out.println(total);       // symbol: variable total

A variable exists only inside the braces where it was declared. Declare it before the block if you need it after, or move the code that uses it inside. The same applies to a variable declared in a try block and used in catch or finally, and to one declared in one branch of an if and used in the other. Move the declaration up to the narrowest scope that contains all the uses.

4. The method does not exist with those arguments

java
String name = "ada";
name.length;                     // symbol: variable length, a method needs ()
name.size();                     // symbol: method size()
name.substring("a");             // symbol: method substring(String)

The symbol: line for a method includes the argument types the compiler saw, which is what makes it useful. method substring(String) means there is no substring that takes a String. Check the documentation for the real signature. When the compiler lists the argument types as something unexpected, such as Object, a generic type was lost earlier in the expression; a raw List returns Object from get. A method added in a newer Java version, such as List.of on Java 8 or String.isBlank before Java 11, also reports a missing symbol. Check the Java version the build uses, which is the subject of the next section.

5. The class is not on the classpath

The code is correct and the library is missing. The compiler cannot see com.fasterxml.jackson.databind.ObjectMapper unless the Jackson jar is a dependency of this module with a scope that includes compilation. In Maven, a dependency with <scope>test</scope> is invisible to main code, and one with provided is visible at compile time only; the rules are in dependency scopes. In Gradle, use implementation or api for main code. After editing the build file, reload the project in the IDE, or run the build from the command line, because the IDE keeps its own copy of the classpath.

A subtler version: the dependency is present but at a version that lacks the class or method you call. Print the resolved tree with mvn dependency:tree and look for an older version winning a conflict. A class file compiled for a newer Java than your compiler fails differently, as described in [UnsupportedClassVersionError](/library/unsupportedclassversionerror-fix-class-file-version-mismatch).

6. Generated code or stale output

Some classes do not exist in the source tree. Lombok creates getters and builders, MapStruct creates mappers, and JPA metamodel and QueryDSL create Q classes, all through annotation processors at compile time. If the processor is not configured, the compiler reports cannot find symbol for getName() or QOrder. Check that the processor is declared in the build, in Maven under annotationProcessorPaths, and that the IDE has annotation processing enabled.

Stale output produces the same message for code that did compile yesterday. Run a clean build:

Shell
mvn clean compile
./gradlew clean compileJava

If a clean build passes and the IDE still shows errors, the IDE's index is out of step; invalidate its caches or reimport the project. If the command line fails and the IDE passes, the IDE is compiling with a different setup, and the command line is right.

Reading a long list of errors

A single typo in a class name can produce dozens of cannot find symbol errors, one for each use. Fix the first error in the output, then recompile, before reading the rest; the later ones are often consequences. A missing import at the top of a file is the classic case, and a missing dependency can generate a hundred errors that all disappear together when the jar is added. The compiler reports only the first hundred by default, so start from the top of the output and not the bottom.

What this error is not

If the name exists but cannot be used, the message is different. incompatible types means the symbol exists and its type is wrong, covered in incompatible types. package does not exist names a missing import of a whole package, and usually points to a missing dependency. An error about a symbol in a module-info file is a different mechanism, requires and exports. The compiler's own options are documented in the [javac manual](https://docs.oracle.com/en/java/javase/25/docs/specs/man/javac.html), and the scoping rules are defined in chapter 6 of the Java Language Specification.

Also inDevOps
Share

Keep reading

Get new posts by email

We send one email when a new post is published. No spam.

Unsubscribe in one click. No spam, ever.