Configuring Main Class for Spring Boot Executable JAR

Problem Background and Error Analysis

During Spring Boot project development, when the project contains multiple classes with main methods, building executable JAR using Spring Boot Maven plugin may encounter the following error:

Execution default of goal org.springframework.boot:spring-boot-maven-plugin:1.0.1.RELEASE:repackage failed: Unable to find a single main class from the following candidates

This error indicates that the Spring Boot plugin encountered ambiguity during automatic main class detection. The plugin scans all classes in the project by default, looking for classes containing public static void main(String[] args) method as entry points. When multiple candidate classes are found, the plugin cannot automatically determine which one should be used as the JAR startup class.

Maven Project Configuration Solutions

Method 1: Using Properties Configuration

Define the main class through <properties> tag in pom.xml file:

<properties>
    <!-- Specify main class for java -jar command execution -->
    <start-class>com.mycorp.starter.HelloWorldApplication</start-class>
</properties>

The advantage of this method lies in its concise configuration and consistency with Spring Boot's default configuration mechanism. The start-class property is automatically recognized and used by Spring Boot Maven plugin.

Method 2: Direct Plugin Configuration

Explicitly specify the main class directly in Spring Boot Maven plugin configuration:

<build>
<plugins>
    <plugin>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-maven-plugin</artifactId>             
        <configuration>    
            <mainClass>com.mycorp.starter.HelloWorldApplication</mainClass>
        </configuration>
    </plugin>
</plugins>
</build>

This method provides a more direct configuration approach, particularly suitable for precise control of plugin behavior in complex multi-module projects.

Special Case: Without spring-boot-starter-parent

For projects not using Spring Boot official parent POM, more complete plugin configuration is required:

<plugin>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-maven-plugin</artifactId>
    <version>1.1.3.RELEASE</version>
    <configuration>
        <mainClass>my.package.MyStartClass</mainClass>
        <layout>ZIP</layout>
    </configuration>
    <executions>
        <execution>
            <goals>
                <goal>repackage</goal>
            </goals>
        </execution>
    </executions>
</plugin>

This configuration ensures correct plugin version and execution goals while supporting custom packaging layouts.

Gradle Project Configuration

For projects using Gradle as build tool, configure the main class as follows:

springBoot {
    mainClass = "com.example.Main"
}

Gradle configuration is relatively concise, but proper configuration of Spring Boot Gradle plugin must be ensured. In actual projects, correct dependency management and classpath configuration should also be verified.

In-depth Understanding and Best Practices

Plugin Working Mechanism Analysis

When Spring Boot build plugin executes the repackage goal, it performs the following steps:

1. Scans all class files in project compilation output directory
2. Identifies classes containing main methods
3. Throws error if multiple candidate classes found without explicit main class specification
4. Repackages original JAR into executable JAR with appropriate launcher embedded

Understanding this process helps better configure build parameters in complex projects.

Common Issue Troubleshooting

Based on experiences from related technical articles, when encountering "main class not found" errors, check the following aspects:

• Ensure main class package path is completely correct in configuration
• Verify if build tool correctly recognizes runtime classpath
• Check environment differences between IDE execution and command line execution
• Confirm plugin version compatibility with Spring Boot version

Configuration Selection Recommendations

Choose appropriate configuration methods based on project characteristics:

• Simple projects: Recommend using <properties> configuration for concise setup
• Complex multi-module projects: Suggest explicit specification in plugin configuration for better readability
• Custom builds: Require complete plugin parameter and version configuration
• Gradle projects: Use dedicated Spring Boot configuration blocks

Through proper main class configuration, Spring Boot applications can ensure correct startup in various deployment environments, avoiding runtime errors caused by classpath issues.