Introduction

IntelliJ's "Package doesn't exist" error means the compiler cannot locate a package referenced in an import statement. The most common causes are: the dependency is missing from your build file (pom.xml or build.gradle), the source directory is not marked as a Sources Root, or IntelliJ's internal caches are out of sync. Each of these has a specific fix, and this article walks through all of them systematically.

How IntelliJ Resolves Packages

IntelliJ resolves packages by consulting three sources:

1. Source roots. Directories marked as "Sources Root" in the project structure. Java files under these directories form the project's own packages.
2. Dependencies. Libraries declared in Maven (pom.xml), Gradle (build.gradle), or added manually to the project's module dependencies.
3. JDK modules. Standard library packages provided by the configured JDK (e.g., java.util, java.io).

If a package cannot be found in any of these sources, IntelliJ reports "Package doesn't exist" during compilation. The error can also appear as red underlines in the editor before you even compile.

Cause 1: Missing Dependency

The most common cause. The package belongs to an external library that has not been added to the project's build configuration.

Maven

1<!-- pom.xml -->
2<dependencies>
3    <dependency>
4        <groupId>com.google.guava</groupId>
5        <artifactId>guava</artifactId>
6        <version>33.0.0-jre</version>
7    </dependency>
8</dependencies>

After adding the dependency, reload the Maven project:

• Press Ctrl+Shift+O (Windows/Linux) or Cmd+Shift+I (macOS) when IntelliJ shows the "Load Maven Changes" notification
• Or right-click the pom.xml and select Maven > Reload Project

Gradle

1// build.gradle
2dependencies {
3    implementation 'com.google.guava:guava:33.0.0-jre'
4}

Reload the Gradle project:

• Click the Gradle elephant icon in the notification bar
• Or open the Gradle tool window and click the refresh button

Verifying the dependency is resolved

1# Maven
2mvn dependency:tree | grep guava
3
4# Gradle
5./gradlew dependencies --configuration runtimeClasspath | grep guava

If the dependency does not appear in the tree, the build file has a syntax error or the dependency coordinates are wrong.

Cause 2: Source Directory Not Marked as Sources Root

IntelliJ needs to know which directories contain source code. If a directory is not marked correctly, all packages under it become invisible.

Symptoms

• Code compiles fine from the command line (mvn compile or ./gradlew build succeeds)
• IntelliJ shows red underlines and "Package doesn't exist" in the editor
• The directory icon in the Project view is gray instead of blue

Fix

1. Right-click the directory (typically src/main/java)
2. Select Mark Directory as > Sources Root

For test directories, mark them as Test Sources Root (src/test/java).

In a standard Maven or Gradle project, IntelliJ should detect these automatically. If it does not, the project import may have failed. Re-import the project:

• File > Invalidate Caches... > Invalidate and Restart (nuclear option)
• Or delete the .idea directory and re-open the project

Project structure for reference

1my-project/
2  src/
3    main/
4      java/           <-- Sources Root (blue folder)
5        com/
6          example/
7            MyClass.java
8      resources/       <-- Resources Root
9    test/
10      java/           <-- Test Sources Root (green folder)
11  pom.xml

Cause 3: IntelliJ Caches Out of Sync

IntelliJ maintains internal indexes and caches for fast code navigation. These can occasionally fall out of sync with the actual project state, especially after branch switches, merges, or external build tool changes.

Quick fix: Invalidate caches

File > Invalidate Caches... > Invalidate and Restart

This clears all internal caches and forces IntelliJ to re-index the entire project. It takes a few minutes on large projects but resolves most phantom errors.

Reimport the build model

For Maven:

Right-click pom.xml > Maven > Reimport

For Gradle:

Open the Gradle tool window > click the refresh (sync) icon

Delete .idea and .iml files

As a last resort, close the project and delete the .idea directory and any .iml files. Then reopen the project. IntelliJ regenerates these from the build files.

# From the project root
rm -rf .idea
find . -name "*.iml" -delete

Cause 4: Wrong JDK Version

If the project uses APIs from a newer JDK than what IntelliJ is configured to use, packages like java.net.http (Java 11+) or java.util.stream.Gatherers (Java 22+) will appear missing.

Check the project SDK

File > Project Structure > Project > SDK

Ensure the JDK version matches what the project expects. Check the build file:

1<!-- Maven -->
2<properties>
3    <maven.compiler.source>21</maven.compiler.source>
4    <maven.compiler.target>21</maven.compiler.target>
5</properties>

1// Gradle
2java {
3    sourceCompatibility = JavaVersion.VERSION_21
4    targetCompatibility = JavaVersion.VERSION_21
5}

Check module language level

File > Project Structure > Modules > Sources > Language Level

Each module can have its own language level. If this is set to a version lower than the source code requires, certain packages and language features will not resolve.

Cause 5: Multi-Module Project Misconfiguration

In multi-module Maven or Gradle projects, IntelliJ sometimes fails to recognize inter-module dependencies.

Symptoms

• Module A uses classes from Module B
• IntelliJ shows "Package doesn't exist" for Module B's packages
• Command-line build works fine

Fix for Maven

Ensure Module A declares a dependency on Module B:

1<!-- Module A's pom.xml -->
2<dependencies>
3    <dependency>
4        <groupId>com.example</groupId>
5        <artifactId>module-b</artifactId>
6        <version>${project.version}</version>
7    </dependency>
8</dependencies>

Then reimport the Maven project.

Fix for Gradle

1// Module A's build.gradle
2dependencies {
3    implementation project(':module-b')
4}

Then sync the Gradle project.

Cause 6: Typo in Import Statement

Sometimes the issue is simply a wrong package name:

1// Wrong: lowercase 'a' in ArrayList's package
2import java.util.arraylist;  // Package doesn't exist
3
4// Correct
5import java.util.ArrayList;

Use IntelliJ's auto-import feature (Alt+Enter on the unresolved symbol) to get the correct import. This avoids typos entirely.

Systematic Debugging Checklist

If the command-line build succeeds but IntelliJ fails, the problem is always in IntelliJ's configuration, not in the code.

Common Pitfalls

• Adding a dependency to the wrong module. In multi-module projects, each module has its own build file. The dependency must be declared in the module that uses it, not just in the root or parent project.
• Not reloading the Maven/Gradle project after editing the build file. IntelliJ does not automatically pick up changes to pom.xml or build.gradle. You must trigger a reimport manually or enable auto-import in settings.
• Confusing the JDK version with the language level. The project SDK might be JDK 21, but the module language level could be set to 11. In that case, APIs introduced after JDK 11 will not resolve.
• Leaving stale .idea or .iml files in version control. If these files reference modules or JDKs that do not exist on another developer's machine, the project opens with errors. Either commit them consistently or .gitignore them.
• Not checking the terminal build first. If mvn compile or ./gradlew build fails, the problem is in the project configuration itself, not in IntelliJ. Fix the build first, then reimport.
• Running Invalidate Caches as the first step. This is a slow operation that should be a last resort. Try reimporting the build model first, which is faster and resolves most issues.

Summary

• The "Package doesn't exist" error in IntelliJ means the compiler cannot locate a package referenced in an import statement.
• The most common cause is a missing dependency in pom.xml or build.gradle. Add the dependency and reimport the project.
• If source directories are not marked as Sources Root, IntelliJ cannot see the packages they contain. Right-click the directory and mark it correctly.
• Stale IntelliJ caches can produce phantom errors. Reimport the build model first; invalidate caches as a last resort.
• Verify the project SDK and module language level match the JDK version the code requires.
• Always test with a command-line build (mvn compile or ./gradlew build) to determine whether the problem is IntelliJ-specific or a genuine build issue.