Introduction

In a multi module Maven project, running spring-boot:run from the parent module can fail if plugin configuration or module selection is unclear. Maven executes plugins in the current project context unless you direct it to a child module. The reliable solution is to target the application module explicitly.

Understand Parent and Child Roles

A parent pom usually has packaging type pom and no runnable application classes. Your Spring Boot app lives in one child module, often named app, web, or service.

From the repository root, run the plugin against that module using -pl and optionally -am to build required dependencies.

mvn -pl app -am spring-boot:run

• -pl app selects the application module.
• -am also builds upstream modules required by app.

This is the most common command for root level execution.

Configure Plugin in the Application Module

Keep spring-boot-maven-plugin in the runnable module, not only in the parent. Parent pluginManagement can define versions, but child modules still need plugin declaration to activate goals.

1<project>
2  <modelVersion>4.0.0</modelVersion>
3  <parent>
4    <groupId>com.example</groupId>
5    <artifactId>parent</artifactId>
6    <version>1.0.0</version>
7  </parent>
8
9  <artifactId>app</artifactId>
10
11  <dependencies>
12    <dependency>
13      <groupId>org.springframework.boot</groupId>
14      <artifactId>spring-boot-starter-web</artifactId>
15    </dependency>
16  </dependencies>
17
18  <build>
19    <plugins>
20      <plugin>
21        <groupId>org.springframework.boot</groupId>
22        <artifactId>spring-boot-maven-plugin</artifactId>
23      </plugin>
24    </plugins>
25  </build>
26</project>

If the plugin is missing in child build plugins, goal resolution can fail even though parent versions are defined.

Profiles and Properties from Parent

Running from root often depends on parent profile defaults, JVM options, and shared properties. You can pass profile and application arguments directly through Maven.

mvn -pl app -am spring-boot:run   -Dspring-boot.run.profiles=local   -Dspring-boot.run.arguments="--server.port=8085"

This keeps environment setup reproducible for the team and CI tasks.

Troubleshooting Command Failures

If Maven cannot find the selected module, check modules in parent pom and confirm module directory names match -pl selector. You can also use group and artifact coordinates for clarity.

If Spring Boot reports no main class, verify that the app module contains a valid @SpringBootApplication entry point and that packaging settings are correct.

When startup uses stale classes, run mvn -pl app -am clean spring-boot:run to force recompilation.

Another useful option is running from inside the app module directory when debugging plugin behavior:

cd app
mvn spring-boot:run

This bypasses reactor module selection issues and helps isolate whether root level command flags are the cause. Once stable, move back to parent level commands for consistent team workflows.

In CI, keep one scripted entry point for local and pipeline runs so developers do not maintain separate command variants. A Makefile or wrapper script around Maven commands can standardize options and reduce setup friction for new contributors. Teams can then update one command definition when build flags change, which lowers maintenance overhead and onboarding time.

Common Pitfalls

A common pitfall is running spring-boot:run on the parent pom module directly. Parent modules are aggregators and usually not executable.

Another issue is defining plugin versions only in parent pluginManagement and forgetting to declare the plugin in child modules.

Developers also skip -am, then wonder why dependent local modules are not built. Include it when app module depends on sibling modules.

Finally, mismatched Java version settings between parent and child can cause runtime startup errors. Keep toolchain properties centralized and consistent.

Summary

• Use mvn -pl app -am spring-boot:run from the parent directory.
• Declare Spring Boot plugin in the runnable child module.
• Use parent pluginManagement for versions, not goal activation.
• Pass profiles and app arguments through Maven properties.
• Confirm module selection and main class setup when troubleshooting startup issues in shared repositories and CI environments consistently for teams daily use.