Introduction

When IntelliJ shows "Cannot resolve symbol" but your code compiles and runs fine, the issue is a mismatch between IntelliJ's internal project model and your actual build configuration. IntelliJ maintains its own index of classes, methods, and dependencies for real-time code assistance, and this index can fall out of sync with what Maven, Gradle, or your JDK actually provides. The code compiles because the build tool uses its own classpath resolution, which is correct. The fix is almost always one of three things: reimport your build project, invalidate IntelliJ's caches, or correct the SDK/module configuration.

Why This Happens

IntelliJ runs two separate systems in parallel:

1. The IDE's internal compiler and indexer: This powers syntax highlighting, auto-completion, navigation, and error inspections. It builds a model of your project by parsing source files and reading dependency metadata.
2. The external build tool (Maven, Gradle, or javac directly): This handles actual compilation using its own classpath, dependency resolution, and compiler settings.

When these two systems disagree about what classes and methods are available, you get the "Cannot resolve symbol" inspection error even though compilation succeeds.

Root Causes

Fix 1: Reimport the Build Project

This is the most common fix and should be your first action.

For Maven:

1. Open the Maven tool window (View > Tool Windows > Maven).
2. Click the Reload All Maven Projects button (circular arrows icon at the top).

Or use the keyboard: press Ctrl+Shift+A (or Cmd+Shift+A on macOS), type "Reload All Maven Projects," and press Enter.

For Gradle:

1. Open the Gradle tool window.
2. Click the Reload All Gradle Projects button.

This forces IntelliJ to re-read your build files, re-resolve dependencies, and update its internal project model.

From the command line (useful when the IDE is stuck):

1# Maven: force dependency re-download and update
2mvn dependency:purge-local-repository
3mvn clean install
4
5# Gradle: refresh dependencies
6./gradlew --refresh-dependencies build

After running these, reimport the project in IntelliJ.

Fix 2: Invalidate Caches and Restart

If reimporting does not help, the IDE's index may be corrupted.

1. Go to File > Invalidate Caches.
2. Check all options in the dialog.
3. Click Invalidate and Restart.

IntelliJ will restart and rebuild its entire index from scratch. This takes a few minutes on large projects but resolves most index corruption issues.

File > Invalidate Caches > Check all boxes > Invalidate and Restart

After restart, wait for the indexing progress bar at the bottom of the IDE to complete before checking whether the errors are gone.

Fix 3: Check the Project SDK and Language Level

A mismatch between the configured SDK and the actual JDK features you are using causes resolution failures for newer APIs.

1. Go to File > Project Structure > Project.
2. Verify the SDK is set to the correct JDK version.
3. Verify the Language Level matches (e.g., "17" for JDK 17 features).

File > Project Structure > Project
  SDK: corretto-17 (or your JDK)
  Language Level: 17

Also check each module individually:

1. Go to File > Project Structure > Modules.
2. Select each module and verify its Language Level is not set to a lower version than the project default.

Fix 4: Check Source Root Configuration

IntelliJ only indexes directories marked as source roots. If a directory is not marked, its classes are invisible to the IDE.

1. Go to File > Project Structure > Modules.
2. Select the module and click the Sources tab.
3. Verify that src/main/java is marked as Sources (blue folder).
4. Verify that src/test/java is marked as Tests (green folder).
5. If annotation processors generate code to target/generated-sources/annotations, mark it as Generated Sources Root.

For Maven projects, reimporting usually sets these correctly. For manually configured projects, you may need to set them yourself.

Fix 5: Regenerate Generated Sources

If the unresolved symbols come from code generators like Lombok, MapStruct, or Dagger, the generated sources may not exist yet.

1# Maven: run annotation processing
2mvn compile
3
4# Gradle: run annotation processing
5./gradlew compileJava

Then in IntelliJ:

1. Go to Settings > Build, Execution, Deployment > Compiler > Annotation Processors.
2. Ensure Enable annotation processing is checked.
3. Reimport the project.

For Lombok specifically, install the Lombok IntelliJ plugin (Settings > Plugins > search "Lombok") in addition to having the Lombok dependency in your build file.

Fix 6: Delete .idea and Reimport (Nuclear Option)

If nothing else works, remove IntelliJ's project configuration entirely:

1# Close IntelliJ first
2rm -rf .idea
3rm -f *.iml
4rm -f **/*.iml

Then reopen the project in IntelliJ by opening the pom.xml or build.gradle file as a project. IntelliJ will create a fresh .idea directory with a clean project configuration.

This loses any custom run configurations, code style overrides, and inspection profiles that were stored in .idea. If your team checks .idea files into version control, restore them from Git after the reimport.

Diagnostic Checklist

Use this quick reference to work through the issue systematically:

Start from the top and stop at the step that fixes the issue.

Common Pitfalls

• Jumping straight to "Invalidate Caches": This triggers a full re-index that takes minutes. In most cases, a simple reimport (step 1) fixes the problem in seconds.
• Ignoring the background indexing bar: After invalidating caches or reimporting, IntelliJ needs time to re-index. Checking for errors before indexing completes gives false results. Wait for the progress bar at the bottom to finish.
• Using "Build > Build Project" instead of reimporting: Building the project does not update IntelliJ's dependency model. If the issue is a missing dependency, building will not help. Reimporting is the correct action.
• Multiple JDKs installed without specifying which one: If you have JDK 8, 11, and 17 installed, IntelliJ may pick a different one than your build tool. Explicitly set the SDK in Project Structure.
• Lombok without the IntelliJ plugin: The Lombok dependency in pom.xml enables compilation, but IntelliJ needs the Lombok plugin to understand @Getter, @Setter, and other annotations during indexing. Without the plugin, every Lombok-generated method shows as unresolved.
• Trusting the red squiggles over the build tool: If mvn clean install succeeds, the code is correct. The IDE is wrong. This distinction matters when deciding whether to change code or fix IDE configuration.

Summary

• "Cannot resolve symbol" with successful compilation means IntelliJ's project model is out of sync with the build tool.
• Start with a Maven/Gradle reimport, which fixes the majority of cases.
• Check the Project SDK and language level if newer Java features are unresolved.
• Invalidate caches only when reimporting does not help, as it triggers a full re-index.
• For generated sources (Lombok, MapStruct), run the build to generate code and enable annotation processing in IntelliJ settings.
• As a last resort, delete the .idea directory and reimport the project from scratch.
• Always wait for indexing to complete after any of these actions before evaluating the result.