When IntelliJ IDEA shows a Java file with a yellow background and the warning "Java file outside of source root," it means the file is not inside a directory that IntelliJ recognizes as a source root. The fix is to mark the correct directory as a Sources Root in Project Structure settings. This warning is not a compilation error from Java itself; it is IntelliJ telling you that it cannot provide code completion, refactoring, or compilation for that file because it does not know where the file belongs in the project's source tree.

What Source Roots Are

IntelliJ uses source roots to determine which directories contain compilable source code, test code, resources, and generated files. The IDE relies on this classification for:

• Resolving package declarations and imports
• Providing code completion and navigation
• Compiling code with the correct classpath
• Running tests from the correct source sets
• Indexing only relevant files for search

A typical Maven or Gradle project has these standard source roots:

1project-root/
2  src/
3    main/
4      java/          <-- Sources Root (blue folder)
5      resources/     <-- Resources Root
6    test/
7      java/          <-- Test Sources Root (green folder)
8      resources/     <-- Test Resources Root
9  build/
10    generated/
11      sources/       <-- Generated Sources Root (if applicable)

If you create a Java file outside any of these directories, or if IntelliJ has not imported the project correctly, you will see the "outside of source root" warning.

How to Fix It: Mark as Sources Root

Method 1: Right-Click in the Project View

The fastest way to fix a single directory:

1. Open the Project tool window (Alt+1 / Cmd+1)
2. Right-click the directory that should be a source root
3. Select Mark Directory as then Sources Root

The folder icon turns blue, and IntelliJ immediately re-indexes the files inside it.

Method 2: Project Structure Dialog

For a more complete view of all modules and their source roots:

1. Open File then Project Structure (Ctrl+Alt+Shift+S / Cmd+;)
2. Select Modules in the left panel
3. Click the module containing the file
4. Switch to the Sources tab
5. In the directory tree, click the folder you want to mark
6. Click the Sources button at the top of the tree (or right-click and select the root type)
7. Click Apply then OK

1Project Structure > Modules > [your module] > Sources tab
2
3Directory tree:
4  [project-root]
5    [src]
6      [main]
7        [java]  <-- click this, then click "Sources" button
8      [test]
9        [java]  <-- click this, then click "Tests" button

Method 3: Re-import the Build Tool Configuration

If your project uses Maven or Gradle, the simplest fix is to let the build tool configure source roots automatically:

1For Maven:
2  Right-click pom.xml > Maven > Reimport
3  Or: Maven tool window > Reload button
4
5For Gradle:
6  Right-click build.gradle > Gradle > Reimport Project
7  Or: Gradle tool window > Reload button
8  Or: File > Invalidate Caches and Restart (nuclear option)

After re-import, IntelliJ reads the build configuration and sets all source roots based on the sourcesets (Gradle) or standard directory layout (Maven).

Common Causes and Solutions

Verifying the Fix

After marking source roots, verify that IntelliJ properly recognizes your files:

1// This file should now show:
2// - Correct package declaration (matching directory structure)
3// - Working code completion (Ctrl+Space)
4// - No yellow background
5// - Ability to run/debug
6package com.example.myapp;
7
8public class Application {
9    public static void main(String[] args) {
10        System.out.println("File is inside source root");
11    }
12}

If the package declaration does not match the directory path relative to the source root, IntelliJ will show a different error: "Package name does not correspond to the file path." This means the source root is set, but at the wrong level.

1Correct:
2  Source root: src/main/java/
3  File path:   src/main/java/com/example/Main.java
4  Package:     com.example
5
6Wrong (source root too deep):
7  Source root: src/main/java/com/
8  File path:   src/main/java/com/example/Main.java
9  Package:     example  (IntelliJ expects this, but file declares com.example)
10
11Wrong (source root too shallow):
12  Source root: src/
13  File path:   src/main/java/com/example/Main.java
14  Package:     main.java.com.example  (IntelliJ expects this based on directory depth)

Gradle and Maven Source Set Configuration

If you need non-standard source directories, configure them in your build tool so IntelliJ picks them up automatically on import.

Gradle

1// build.gradle
2sourceSets {
3    main {
4        java {
5            srcDirs = ['src/main/java', 'src/generated/java']
6        }
7        resources {
8            srcDirs = ['src/main/resources', 'config']
9        }
10    }
11    test {
12        java {
13            srcDirs = ['src/test/java', 'src/integration-test/java']
14        }
15    }
16}

Maven

1<!-- pom.xml -->
2<build>
3    <sourceDirectory>src/main/java</sourceDirectory>
4    <testSourceDirectory>src/test/java</testSourceDirectory>
5    <plugins>
6        <plugin>
7            <groupId>org.codehaus.mojo</groupId>
8            <artifactId>build-helper-maven-plugin</artifactId>
9            <executions>
10                <execution>
11                    <id>add-source</id>
12                    <phase>generate-sources</phase>
13                    <goals><goal>add-source</goal></goals>
14                    <configuration>
15                        <sources>
16                            <source>src/generated/java</source>
17                        </sources>
18                    </configuration>
19                </execution>
20            </executions>
21        </plugin>
22    </plugins>
23</build>

After updating the build file, re-import the project and IntelliJ will configure the source roots to match.

Common Pitfalls

• Marking the wrong directory level as source root. If you mark src/ instead of src/main/java/, IntelliJ will expect packages starting with main.java.com.example, which breaks everything. The source root must be the directory directly above your top-level package.
• Forgetting to re-import after editing build.gradle or pom.xml. IntelliJ does not automatically detect source set changes in build files. You must trigger a re-import.
• Deleting .idea/ without re-importing. If you delete the IDE configuration directory to fix issues, you must re-import the project afterward. Opening the directory without importing loses all module and source root configuration.
• Creating Java files before setting up the project. If you create .java files in a plain directory and then try to turn it into a project, IntelliJ may not auto-detect the structure. Import via the build tool first, then create files.
• Confusing content roots with source roots. A content root is the top-level directory IntelliJ associates with a module. A source root is a subdirectory within a content root that contains compilable code. You need both configured correctly.
• Ignoring the warning because the code compiles from the command line. Maven and Gradle compile based on their own configuration, independent of IntelliJ. The IDE warning means IntelliJ-specific features (refactoring, navigation, debugging) will not work correctly for that file.

Summary

The "Java file outside of source root" warning means IntelliJ does not know where your source code lives. Fix it by marking the correct directory as a Sources Root (right-click the folder, or use Project Structure settings), or by re-importing your Maven/Gradle project so IntelliJ reads the build configuration. The source root must be set at the directory level directly above your top-level Java package. For non-standard layouts, configure sourceSets in Gradle or use build-helper-maven-plugin in Maven, then re-import. Always verify the fix by checking that code completion works and the package declaration matches the directory structure relative to the source root.