Short version: “Cannot resolve symbol” usually means the IDE can’t find a class, method, field or package you referenced. That can be because of a missing import, wrong project/JDK setup, a missing dependency, excluded source folder, broken index, or an annotation processor (like Lombok) not configured. Below I’ll walk you through simple, actionable baby steps for IntelliJ IDEA and VS Code so you can fix it fast — plus deeper fixes and prevention tips.
Quick checklist — Try these first (fast wins)
Press Alt+Enter (Option+Enter on macOS) on the red symbol — does the IDE offer to import it? Accept it.
Rebuild the project: Build → Rebuild Project (IntelliJ) or run mvn clean install / ./gradlew build in terminal.
Re-import your build file: click Reload All Maven Projects or Refresh Gradle Project.
In IntelliJ: File → Invalidate Caches / Restart... → Invalidate and Restart.
In VS Code: open Command Palette (Ctrl+Shift+P) → Java: Clean the Java Language Server Workspace → restart.
Check that your Java SDK / JDK is configured and consistent between IDE and terminal.
Ensure the file is inside a marked source root (e.g., src/main/java) and package path matches the package statement.
If one of those immediately fixed it — great. If not, read on for step-by-step troubleshooting.
What “Cannot resolve symbol” actually means
IDE level: The language server/indexer doesn’t know where the symbol (class, method, field) is.
Compiler-level (javac): If the compiler itself fails with “cannot find symbol”, dependencies or imports are missing at build time.
They’re related but slightly different: IDE issues are often indexing/config problems; compiler issues mean your project classpath/build file is wrong.
Part A — IntelliJ IDEA: step-by-step fixes (baby steps)
1) Confirm you’re using a proper Project SDK (JDK)
File → Project Structure... (Ctrl+Alt+Shift+S)
Under Project, check Project SDK is set (e.g., Java 17). If empty, Add SDK → point to your JDK installation.
Under Project language level, pick an appropriate level.
Why this matters: If no JDK, standard Java classes (List, String, etc.) can’t be resolved.
2) Ensure modules have correct SDK and dependencies
File → Project Structure → Modules → select your module.
Go to Dependencies tab: verify module SDK and listed libraries/dependencies.
If your other module/class is in a different module, add a Module Dependency (click + → Module Dependency).
3) Make sure source folders are marked correctly
In Project view, right-click your src/main/java folder → Mark Directory as → Sources Root (it becomes blue).
If the folder is not a source root, classes inside won’t be visible to the compiler/IDE.
4) Check imports and package statement (baby steps)
Open the file with the red symbol.
If an import is missing, press Alt+Enter → choose Import class.
Confirm package com.example.app; at the top matches the folder path: src/main/java/com/example/app/YourClass.java.
Common trap: on Linux/macOS the file system is case-sensitive, so MyClass vs myclass matters.
5) Re-import Maven / Gradle project
Maven: open Maven tool window → click the Reload All Maven Projects icon.
Gradle: open Gradle tool window → click the Refresh icon.
Or run in terminal:
# Maven mvn -U clean install # Gradle (Unix) ./gradlew clean build --refresh-dependencies # Windows gradlew.bat clean build --refresh-dependencies
This ensures declared dependencies are actually downloaded and on your classpath.
6) Annotation processors and Lombok
If the unresolved symbol is an annotation-generated method/field (e.g., Lombok @Data, @Builder):
IntelliJ:
Install the Lombok plugin (Settings → Plugins → search Lombok → Install).
Settings → Build, Execution, Deployment → Compiler → Annotation Processors → Enable annotation processing.
Rebuild the project.
Maven example dependency (pom.xml snippet):
<dependency> <groupId>org.projectlombok</groupId> <artifactId>lombok</artifactId> <version>1.18.26</version> <scope>provided</scope> </dependency>
Gradle example:
dependencies { compileOnly 'org.projectlombok:lombok:1.18.26' annotationProcessor 'org.projectlombok:lombok:1.18.26' }
7) Indexing, caches, and rebuild
If IntelliJ’s index is corrupted:
File → Invalidate Caches / Restart... → Invalidate and Restart.
After restart, IntelliJ re-indexes. This fixes many weird unresolved-symbol issues.
Also try: Build → Rebuild Project.
8) Module-Path vs Classpath (Java 9+ module system)
If your project uses module-info.java:
Make sure your module-info.java lists the required modules, e.g.
module my.app { requires transitive org.apache.commons.lang3; }
If the dependency is a classpath library (not a module), consider removing module-info.java temporarily or adjusting how you configure modules.
9) Final IntelliJ rescue: re-import the project
If nothing works:
Close project.
Delete .idea/ folder and *.iml files (back them up if needed).
Re-open IntelliJ → Open → select pom.xml or build.gradle to re-import the project cleanly.
Part B — Visual Studio Code (Java) — baby steps
VS Code uses a language server for Java. Many “cannot resolve symbol” problems occur because the Java language server hasn’t indexed or build files aren’t imported.
1) Install Java extensions
Install Extension Pack for Java (includes Red Hat Java language support, Debugger, Maven/Gradle support). Restart VS Code.
2) Make sure java.home / runtime is configured
Open settings.json or UI Settings:
"java.home": "C:\\Program Files\\Java\\jdk-17", "java.configuration.runtimes": [ { "name": "JavaSE-17", "path": "C:\\Program Files\\Java\\jdk-17", "default": true } ]
Set to your JDK path. On macOS/Linux use the matching path.
3) Rebuild / refresh build tools
For Maven: use the Maven explorer → right-click project → Update Project (or use command palette Maven: Update Project).
For Gradle: use Gradle Tasks view → refresh.
4) Clean Java language server workspace
Command Palette (Ctrl+Shift+P) → Java: Clean the Java Language Server Workspace → restart the window.
5) Ensure source folders are correct
Make sure src/main/java exists and files use proper package declaration and folder layout.
6) If using Lombok or annotation processors
Install Lombok plugin for VS Code or ensure Lombok dependency present and annotation processing configured in Gradle/Maven.
For Lombok, you may still need to add the lombok jar to the classpath or ensure the build tool compiles correctly.
7) If using multiple workspaces or multi-root workspace
Open the correct workspace root (where pom.xml or build.gradle lives). VS Code only indexes workspace folders that are actually opened.
8) When VS Code shows red squiggles but mvn compile works
This means the language server (IDE) is out of sync. Reimport/refresh project and run Java: Restart Language Server or clean once more.
Part C — Common scenarios + concrete fixes (copy-paste examples)
Scenario: “Cannot resolve symbol: SomeLibClass”
Fix: add dependency to pom.xml or build.gradle
Maven
<dependency> <groupId>com.example</groupId> <artifactId>somelib</artifactId> <version>1.2.3</version> </dependency>
Then re-import Maven and mvn clean install.
Gradle (Groovy)
dependencies { implementation 'com.example:somelib:1.2.3' }
Then ./gradlew clean build and refresh Gradle in the IDE.
Scenario: @Data from Lombok shows “Cannot resolve symbol 'toString'` or Lombok-generated methods missing
Fix:
Add Lombok dependency (see earlier).
IntelliJ only: install Lombok plugin and enable annotation processing.
Rebuild.
Scenario: Class in other module cannot be resolved
IntelliJ fix: File → Project Structure → Modules → select module → Dependencies → + → Module Dependency → choose the other module.
Gradle multi-module fix: make sure submodule is declared in settings.gradle and add dependency:
dependencies { implementation project(':other-module') }
Scenario: List or Map not resolved (basic Java classes)
Check Project SDK (IntelliJ) or java.home (VS Code).
Check imports — e.g. import java.util.List; — Alt+Enter to auto-import.
If even java.lang.String unresolved, your JDK is missing/not configured.
Part D — Diagnostic commands & logs (when you need more info)
Run mvn -X clean install to see detailed Maven logs.
Run ./gradlew build --info for Gradle logs.
In IntelliJ: Help → Show Log in Explorer/Finder to open idea.log (look for indexing/build errors).
In VS Code: Help → Toggle Developer Tools → Console for extension errors.
Part E — Prevent this in future (best practices)
Use Maven or Gradle to manage dependencies — don’t manually place jars in lib/.
Keep your java.home and Project SDK consistent across IDE, terminal, CI.
Mark source roots and don't move files without updating package paths.
Use version control for pom.xml / build.gradle. If IntelliJ gets confused, re-import the build file.
Add a CI step that runs mvn -B -q -DskipTests deploy or ./gradlew build to catch missing dependencies early.
Quick troubleshooting matrix (short)
Red squiggle, IDE quick-fix offered → use Alt+Enter.
Symbol unresolved across project → Re-import build file, run build in terminal.
Annotation-generated methods missing → enable annotation processors + plugin.
Class in other module → add module or project dependency.
Standard Java classes not resolved → configure Project SDK / java.home.
Indexing problems / weirdness → Invalidate caches / Restart (IntelliJ) or Clean Language Server (VS Code).
Wrap-up + example “cheat” commands
# Maven quick refresh & build mvn -U clean install # Gradle quick refresh & build ./gradlew clean build --refresh-dependencies # IntelliJ: Invalidate Caches (manual via UI) File → Invalidate Caches / Restart...
If you want, paste one of the following here and I’ll give a targeted fix:
the exact error message + stack trace, or
the pom.xml / build.gradle snippet showing the dependency, or
the small Java file and its package path (folder structure).
I already covered the most common baby-step fixes above — but if you paste a real error and a bit of project setup I’ll point to the exact line that needs changing and provide the exact pom/gradle edit or IDE setting change.