Introduction

When IntelliJ says it cannot find your Spring Boot class, the problem is usually in project metadata rather than in Spring Boot itself. In most cases the class exists, but IntelliJ is launching the wrong module, indexing the wrong source root, or using stale Gradle or Maven data.

Verify the Application Entry Point

Start with the class you expect IntelliJ to run. A Spring Boot entry point must be a normal Java class with a main method, and it must live under production sources such as src/main/java.

1package com.example.demo;
2
3import org.springframework.boot.SpringApplication;
4import org.springframework.boot.autoconfigure.SpringBootApplication;
5
6@SpringBootApplication
7public class DemoApplication {
8    public static void main(String[] args) {
9        SpringApplication.run(DemoApplication.class, args);
10    }
11}

Check four things immediately:

• the file is under src/main/java, not src/test/java
• the package declaration matches the directory layout
• the module containing the class is an application module, not just a shared library
• the class compiles from the command line

If the gutter run icon is missing next to main, IntelliJ is usually not treating the file as a runnable application class. That points to source-root or module setup before it points to Spring Boot.

Fix the Run Configuration and Module Classpath

Open Run | Edit Configurations and inspect the saved configuration carefully. The critical fields are Main class, Use classpath of module, and the selected JDK.

In a multi-module build, IntelliJ can autocomplete the right class name while still launching with the wrong module classpath. That is why this problem shows up often in projects with an aggregator root plus one real application module.

1project-root
2  app
3    src/main/java/com/example/demo/DemoApplication.java
4  common
5    src/main/java/com/example/common/StringUtils.java

In that layout, the run configuration must use the app module classpath. If it uses common or the root aggregator, IntelliJ may fail with a message that the main class cannot be found even though the source file is visible in the editor.

If you use the Spring Boot run configuration type, verify IntelliJ did not silently preserve an old module selection after a rename or reimport. If needed, delete the run configuration and recreate it from the gutter icon on the main method. That usually rebuilds the classpath from the correct module metadata.

Re-sync Gradle or Maven Before Blaming the IDE

IntelliJ builds its idea of modules, output folders, and dependencies from Gradle or Maven. If that imported model is stale, the IDE can look broken while the actual project is fine.

For Gradle, verify the app builds outside IntelliJ:

./gradlew :app:clean :app:bootRun

For Maven, do the equivalent:

mvn -pl app spring-boot:run

If command-line execution works but IntelliJ still cannot find the class, reload the Gradle or Maven project from the IDE tool window. This often fixes run configurations that reference old output directories or old module names.

Also check that annotation processing or generated sources are not part of the issue. While the main Spring Boot class itself is not generated, a broken import can cascade into compilation failures that prevent IntelliJ from producing runnable output.

Confirm Source Roots and Project Structure

Go to Project Structure | Modules and make sure the module is configured the way the build expects:

• 'src/main/java is marked as Sources'
• 'src/main/resources is marked as Resources'
• 'src/test/java is marked as Test Sources'
• the module SDK is valid
• the language level matches the JDK used by the build

It is surprisingly common to import a project after moving directories and end up with plain folders instead of source roots. In that state IntelliJ can open files, index symbols partially, and still refuse to launch the application.

One more useful test is to run the app from the terminal inside IntelliJ. If the shell build works there, your JDK and project files are probably fine, and the remaining problem is the saved run configuration or IDE metadata.

Use the Gutter Icon as a Diagnostic Shortcut

The run icon next to main is a fast way to separate class-discovery problems from configuration problems.

• If the gutter icon runs successfully, the class is valid and your saved configuration is wrong.
• If the gutter icon is missing, IntelliJ does not see the class as a runnable entry point.
• If the gutter icon exists but launch fails, inspect the selected module and JRE.

This shortcut reduces the search space quickly and saves time compared with clearing caches immediately.

Common Pitfalls

The most common mistake is selecting the wrong module under Use classpath of module in a multi-module project. The second most common one is placing the main class under test sources or in a folder that IntelliJ no longer marks as a source root.

Another frequent issue is stale Gradle or Maven import data after renaming modules, changing package paths, or switching branches. Developers also tend to jump straight to Invalidate Caches, but that should come after verifying the entry point, module classpath, and command-line build. Cache invalidation can help, but it is usually treating the symptom rather than confirming the cause.

Summary

• Make sure the Spring Boot class has a real main method and lives under src/main/java.
• Check the run configuration's Main class, module classpath, JDK, and configuration type.
• In multi-module projects, launch with the application module, not the aggregator or shared library module.
• Rebuild and reimport Gradle or Maven if IntelliJ is using stale project metadata.
• Use the gutter icon to determine whether the issue is class discovery or a bad saved configuration.