Maven
Spring Boot
Troubleshooting
Java
Development

mvn spring-bootrun doesn't start spring

Master System Design with Codemia

Enhance your system design skills with over 120 practice problems, detailed solutions, and hands-on exercises.

Introduction

When mvn spring-boot:run does not appear to start your Spring Boot application, the failure is usually in one of a small number of places: the Maven plugin is missing or misconfigured, the app cannot find its main class, startup fails immediately, or the application starts and exits because it is not actually running a web server. The fastest way to fix it is to separate “Maven did not launch” from “Spring launched and then failed.”

Verify the Maven Plugin and Main Class

The spring-boot:run goal comes from the Spring Boot Maven plugin. If that plugin is absent, the command will not know how to launch your app.

A minimal pom.xml setup looks like this:

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

Your application entry point also has to be valid:

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

If the plugin is present but the main class is missing or not on the source path Maven compiles, spring-boot:run will fail before Spring really starts.

Distinguish “Did Not Start” From “Started and Exited”

A common confusion is that the command prints a banner and some logs, then returns to the shell. That often means Spring started successfully but had no reason to keep running.

Typical causes:

  • no web starter on the classpath
  • 'spring.main.web-application-type=none'
  • the app is just a command-line task and finished normally

If you expect a web app, make sure you actually depend on spring-boot-starter-web or another server starter. Otherwise the JVM may exit immediately after startup.

Read the Real Startup Failure

If the process stops with a stack trace, focus on the first meaningful exception, not the final Maven message. Common startup blockers include:

  • port already in use
  • missing configuration properties
  • bean creation failure
  • bad database connection
  • profile-specific config not found

Run with more visibility when needed:

bash
mvn spring-boot:run -X

Or pass Spring arguments directly:

bash
mvn spring-boot:run -Dspring-boot.run.arguments="--debug"

That usually tells you whether the issue belongs to Maven, Spring configuration, or the application itself.

Check the Working Directory and Profiles

spring-boot:run uses your current project layout and runtime configuration. If your app depends on a profile, environment variable, or external file, launching from Maven may behave differently than running from the IDE.

For example:

bash
mvn spring-boot:run -Dspring-boot.run.profiles=dev

If the app works in the IDE but not from Maven, compare:

  • active profiles
  • environment variables
  • JVM options
  • working directory assumptions

The code may be fine while the runtime inputs differ.

Common Pitfalls

The biggest mistake is assuming spring-boot:run failed when the application actually started and exited normally because it is not a server process.

Another mistake is reading only the last Maven line instead of the first Spring exception that explains the real failure.

A third mistake is forgetting that IDE launches often inject profiles, env vars, or classpath differences that mvn spring-boot:run does not automatically reproduce.

Summary

  • Make sure the Spring Boot Maven plugin is present in pom.xml.
  • Verify that your @SpringBootApplication main class is valid and compiled.
  • Check whether the app is failing on startup or starting and exiting normally.
  • Use debug flags to surface the real exception.
  • Compare profiles and runtime inputs with the IDE if Maven behaves differently.

Course illustration
Course illustration

All Rights Reserved.