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.

"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.
src/main/java/dev/javahacks/OrderService.java:14: error: cannot find symbol
List<Order> orders = repository.findAll();
^
symbol: class List
location: class OrderServiceThe 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
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
for (int i = 0; i < 3; i++) {
int total = i * 2;
}
System.out.println(total); // symbol: variable totalA 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
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:
mvn clean compile
./gradlew clean compileJavaIf 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.


