Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/spring-projects/spring-boot/llms.txt

Use this file to discover all available pages before exploring further.

SpringApplication provides numerous hooks for customizing how your application starts, what it displays, how it listens for connections, and how it participates in a servlet container. This guide covers the most common application-level customizations with concrete steps for each.

​
Customize or disable the startup banner

By default, Spring Boot prints an ASCII art banner when the application starts. To replace it, add a banner.txt file to the root of your classpath (src/main/resources/banner.txt). The file supports the following variables:
VariableDescription
${application.version}Version declared in MANIFEST.MF
${application.formatted-version}Version formatted as (v1.0)
${spring-boot.version}Spring Boot version
${spring-boot.formatted-version}Spring Boot version formatted
To disable the banner entirely, set the banner-mode property to off: 
spring:
  main:
    banner-mode: "off"
Or disable it programmatically before the application runs: 
SpringApplication app = new SpringApplication(MyApplication.class);
app.setBannerMode(Banner.Mode.OFF);
app.run(args);

​
Access application arguments programmatically

To access the raw arguments passed on the command line, inject ApplicationArguments into any bean: 
@Component
public class MyBean {

    public MyBean(ApplicationArguments args) {
        boolean debug = args.containsOption("debug");
        List<String> files = args.getNonOptionArgs();
        // ...
    }
}
ApplicationArguments distinguishes between option arguments (those starting with --) and non-option arguments, and gives you access to both.

​
Use Spring application event hooks

Spring Boot publishes several application events before and after the ApplicationContext is created. To listen for them, register an ApplicationListener: 
@Component
public class MyListener implements ApplicationListener<ApplicationStartingEvent> {

    @Override
    public void onApplicationEvent(ApplicationStartingEvent event) {
        // called very early — before beans are created
    }
}
Events are published in this order: ApplicationStartingEvent → ApplicationEnvironmentPreparedEvent → ApplicationContextInitializedEvent → ApplicationPreparedEvent → ApplicationStartedEvent → ApplicationReadyEvent.
Some events are published before the ApplicationContext is created, so you cannot register listeners for them as @Bean definitions. Register them with SpringApplication.addListeners(...) or via META-INF/spring.factories instead.
To customize the Environment or ApplicationContext before refresh, implement EnvironmentPostProcessor and register it in META-INF/spring.factories: 
org.springframework.boot.EnvironmentPostProcessor=com.example.YourEnvironmentPostProcessor

​
Enable lazy initialization

To defer bean creation until first use, enable lazy initialization globally: 
spring:
  main:
    lazy-initialization: true
Use this approach when you want to reduce startup time in development or test environments.
Lazy initialization delays the detection of misconfigured beans from startup time to first use. Problems that would normally cause a fast startup failure may instead surface later under load. Avoid lazy initialization in production unless you have thoroughly tested all code paths.

​
Run on a different port

To change the HTTP port the embedded server listens on: 
server:
  port: 9090
To bind to a random available port (useful in tests): 
server:
  port: 0
To disable the HTTP endpoint entirely and run as a non-web application: 
spring:
  main:
    web-application-type: "none"
You can also set this programmatically: 
SpringApplication app = new SpringApplication(MyApplication.class);
app.setWebApplicationType(WebApplicationType.NONE);
app.run(args);

​
Enable virtual threads

To enable Java 21 virtual threads (Project Loom), set the following property: 
spring:
  threads:
    virtual:
      enabled: true
When virtual threads are enabled, Spring Boot configures the embedded web server (Tomcat, Jetty) and Spring MVC’s @Async executor to use virtual threads automatically.
Virtual threads require Java 21 or later. Verify your build is targeting Java 21 (--release 21) and that your JDK supports them before enabling this option.

​
Use SpringApplicationBuilder for a parent context

To create a parent/child ApplicationContext hierarchy — for example, to share beans between multiple child contexts — use SpringApplicationBuilder: 
new SpringApplicationBuilder()
    .sources(ParentConfiguration.class)
    .child(ChildConfiguration.class)
    .run(args);
Use this approach when you need one context to provide shared infrastructure beans (data sources, security configuration) to several child contexts that each have their own web layer.
SpringApplicationBuilder also exposes a fluent API for setting profiles, banner mode, and other SpringApplication options. It is especially useful when bootstrapping complex, multi-module applications.

​
Troubleshoot auto-configuration

When Spring Boot’s auto-configuration produces unexpected results, enable DEBUG logging to see the auto-configuration decision report: 
java -jar myapp.jar --debug
Or set the log level in application.properties: 
logging.level.org.springframework.boot.autoconfigure=DEBUG
If the Spring Boot Actuator is on the classpath, the /actuator/conditions endpoint renders the same report as JSON for a running application. When reading auto-configuration classes, pay attention to:
  • @ConditionalOnMissingBean — the auto-configuration backs off when you define your own bean.
  • @ConditionalOnClass — the auto-configuration only activates when a specific class is on the classpath.
  • @ConfigurationProperties — identifies the external properties that control the auto-configuration behavior.

​
Create a custom FailureAnalyzer

To intercept a startup exception and produce a human-readable message, extend AbstractFailureAnalyzer: 
public class ProjectConstraintViolationFailureAnalyzer
        extends AbstractFailureAnalyzer<ConstraintViolationException> {

    @Override
    protected FailureAnalysis analyze(Throwable rootFailure, ConstraintViolationException cause) {
        return new FailureAnalysis(
            "Constraint violation: " + cause.getMessage(),
            "Fix the constraint violation and restart.",
            cause);
    }
}
Register the analyzer in META-INF/spring.factories: 
org.springframework.boot.diagnostics.FailureAnalyzer=\
com.example.ProjectConstraintViolationFailureAnalyzer

​
Deploy as a traditional WAR file

To deploy to an external servlet container instead of the embedded one, extend SpringBootServletInitializer and override configure:
1

Extend SpringBootServletInitializer

Modify your main application class (or create a separate one) to extend SpringBootServletInitializer:
@SpringBootApplication
public class MyApplication extends SpringBootServletInitializer {

    @Override
    protected SpringApplicationBuilder configure(SpringApplicationBuilder application) {
        return application.sources(MyApplication.class);
    }

    public static void main(String[] args) {
        SpringApplication.run(MyApplication.class, args);
    }
}
2

Change the packaging to WAR

In pom.xml, set the packaging to war and mark the embedded container as provided:
<packaging>war</packaging>

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-tomcat</artifactId>
        <scope>provided</scope>
    </dependency>
</dependencies>
3

Build and deploy

Build the WAR file and deploy it to your container:
./mvnw package
cp target/myapp.war /path/to/tomcat/webapps/
The main method is preserved so the WAR can still be run as a standalone executable JAR during development: java -jar myapp.war.

Build docs developers (and LLMs) love

Get started for freeTalk to us