SpringApplication: Customizing Startup, Banner, Event Listeners

SpringApplication is the entry point that bootstraps and launches a Spring application. When you call SpringApplication.run(), a carefully orchestrated sequence springs into action: classpath scanning, environment preparation, context creation, bean loading, and finally the moment your app signals it’s ready to handle traffic. Knowing what happens at each step, and having the hooks to customize those steps, is what separates developers who just use Spring Boot from those who actually control it.

This post covers every major customization point: banners (text and image), runner interfaces (ApplicationRunner vs CommandLineRunner), the complete event hierarchy, programmatic configuration via SpringApplicationBuilder, environment post-processing, and the failure scenarios you need to anticipate in production. If you are new to Spring Boot, start with the Spring Boot Roadmap for a structured learning path.

Custom Banner

The startup banner is Spring Boot’s greeting card. Out of the box it prints the Spring Boot version and a ASCII flower graphic. You can replace this with your own branding, display build information, or suppress it entirely for quieter console output.

Text Banner

Create a banner.txt file in src/main/resources/ (classpath root). Spring Boot resolves this automatically at classpath:banner.txt.

 _____  _          __      __         _ _
/ ____|| |        /\ \    / /        | | |
\ `---.| |__     /  \ \  / /_ _ _   _| | |_
 <code>--.\| '_ \   / /\ \ \/ / _</code> | | | | | __|
/\__/ / | | | / ____ \  \ (_| | |_| | | |_
\____/|_| |_|/_/    \_\ \__,_|\__,_|_|\__|
${application.version} | Spring Boot ${spring-boot.version}

The banner supports placeholders and ANSI color codes:

Placeholder	Description
${application.version}	Version from MANIFEST.MF or Implementation-Version
${spring-boot.version}	The running Spring Boot version
${application.title}	Application title from MANIFEST.MF
${Ansi.RED}	ANSI color codes for terminal styling

Image Banner

For pixel-art branding, place a .gif, .png, or .jpg image at classpath:banner.gif (or another supported extension). Spring Boot converts it to ASCII using a built-in converter. Control the image location explicitly:

spring.banner.image.location=classpath:banner.png
spring.banner.image.width=120
spring.banner.image.margin=2
spring.banner.image.invert=false

Programmatic Banner Control

Disable the banner entirely when running tests or in certain environments:

@SpringBootApplication
public class MyApplication {

    public static void main(String[] args) {
        SpringApplication app = new SpringApplication(MyApplication.class);
        app.setBannerMode(Banner.Mode.OFF);
        app.run(args);
    }
}

Or using the builder pattern:

new SpringApplicationBuilder(MyApplication.class)
    .bannerMode(Banner.Mode.OFF)
    .run(args);

With @SpringBootApplication on the main class, you can also use properties:

spring.main.banner-mode=off

The Banner.Mode enum has three values: CONSOLE (print to System.out), LOG (log at INFO level), and OFF (suppress entirely). The default is CONSOLE.

Banner Location Property

When your banner lives outside the default classpath location:

spring.banner.location=file:./custom-banner.txt

Spring Boot registers the resolved banner as a singleton bean named springBootBanner, so you can also replace it entirely by defining your own Banner bean.

Application Runner vs CommandLineRunner

If you need to execute code after Spring Boot finishes starting but before it starts accepting traffic, two interfaces are worth knowing: CommandLineRunner and ApplicationRunner. They do the same job, but they receive arguments differently.

CommandLineRunner

Gets raw String[] arguments directly from main:

@Component
@Order(42)
public class MyCommandLineRunner implements CommandLineRunner {

    @Override
    public void run(String... args) throws Exception {
        System.out.println("Raw args: " + Arrays.toString(args));
    }
}

ApplicationRunner

Gets an ApplicationArguments wrapper instead, which gives you convenient methods for inspecting named options:

@Component
@Order(1)
public class MyApplicationRunner implements ApplicationRunner {

    @Override
    public void run(ApplicationArguments args) throws Exception {
        boolean hasOption = args.containsOption("profile");
        List<String> nonOptionArgs = args.getNonOptionArgs();
        System.out.println("Profile flag present: " + hasOption);
    }
}

Execution Order

Both runner types run after the ApplicationReadyEvent is published. When you have multiple runners, they sort by Ordered value ascending (lower numbers run first). @Order(1) runs before @Order(42). Ties are broken by bean name alphabetically.

@Component
public class AlphaRunner implements ApplicationRunner {
    @Override
    public void run(ApplicationArguments args) { System.out.println("Alpha"); }
}

@Component
@Order(1)
public class FirstRunner implements ApplicationRunner {
    @Override
    public void run(ApplicationArguments args) { System.out.println("First"); }
}

Output: First, then Alpha.

When to Choose Which

Aspect	CommandLineRunner	ApplicationRunner
Argument format	Raw String[]	Parsed ApplicationArguments
Option parsing	Manual	Built-in containsOption(), getOptionValues()
Named arguments	String comparison	args.getOptionValues(“name”)
Use case	Pass-through to legacy code	Structured argument handling

For most Spring Boot applications, ApplicationRunner is the better choice because it handles argument parsing that you’d otherwise have to write yourself.

Application Events and Listeners

Spring Boot publishes a sequence of events from the moment SpringApplication.run() is called until the application is fully running or has failed. You can hook into each phase if you know the order.

The Event Sequence

graph TD
    A[ApplicationStartingEvent] --> B[ApplicationEnvironmentPreparedEvent]
    B --> C[ApplicationContextInitializedEvent]
    C --> D[ApplicationPreparedEvent]
    D --> E[ContextRefreshedEvent]
    E --> F[ApplicationStartedEvent]
    F --> G[LivenessState.CORRECT]
    G --> H[ApplicationReadyEvent]
    H --> I[ReadinessState.ACCEPTING_TRAFFIC]
    A -.-> J[ApplicationFailedEvent]
    D -.-> J

Event Details

ApplicationStartingEvent fires earliest, before the Environment or ApplicationContext exists. Listeners must be registered programmatically via SpringApplication.addListeners() or through spring.factories (or org.springframework.boot.BootstrapConfiguration in Spring Boot 3.x).

ApplicationEnvironmentPreparedEvent fires once the ConfigurableEnvironment is ready. At this point you can modify property sources, add profiles, or inspect configuration.

ApplicationContextInitializedEvent fires after the ApplicationContext is constructed and ApplicationContextInitializers have been called, but before bean definitions are loaded.

ApplicationPreparedEvent fires after the context is fully prepared with bean definitions loaded, but before refresh.

ApplicationStartedEvent fires after the context has been refreshed. At this point the app has started but CommandLineRunner and ApplicationRunner beans have not yet executed.

ApplicationReadyEvent fires after runners complete. The application is fully operational.

ApplicationFailedEvent fires whenever startup fails, with access to the thrown exception and the (partial or null) context.

Registering Listeners

As a Bean (context-available events)

For events fired after the ApplicationContext exists, annotate a bean with @Component and implement ApplicationListener<EventType>:

@Component
public class MyStartupListener implements ApplicationListener<ApplicationReadyEvent> {

    private static final Logger log = LoggerFactory.getLogger(MyStartupListener.class);

    @Override
    public void onApplicationEvent(ApplicationReadyEvent event) {
        log.info("Application ready. Uptime: {} ms",
            System.currentTimeMillis() - event.getTimestamp());
    }
}

Programmatic Registration (early events)

For ApplicationStartingEvent and ApplicationEnvironmentPreparedEvent, the context does not yet exist, so @Bean listeners won’t be found. Register listeners before run() completes:

public static void main(String[] args) {
    SpringApplication app = new SpringApplication(MyApplication.class);
    app.addListeners(new MyEarlyListener());
    app.run(args);
}

Or via SpringApplicationBuilder:

new SpringApplicationBuilder(MyApplication.class)
    .listeners(new MyEarlyListener())
    .run(args);

Via spring.factories (Spring Boot 2.x) / META-INF/spring/org.springframework.boot.BootstrapConfiguration (Spring Boot 3.x)

For auto-configuration scenarios, register listeners in the SpringFactoriesLoader format.

SpringApplicationEvent Hierarchy

All Spring Boot application events extend SpringApplicationEvent, which itself extends Spring Framework’s ApplicationEvent:

ApplicationEvent (Spring Framework)
  └── SpringApplicationEvent
        ├── ApplicationStartingEvent
        ├── ApplicationEnvironmentPreparedEvent
        ├── ApplicationContextInitializedEvent
        ├── ApplicationPreparedEvent
        ├── ApplicationStartedEvent
        ├── ApplicationReadyEvent
        └── ApplicationFailedEvent

Standard Spring Framework events like ContextRefreshedEvent (from AbstractApplicationContext) also fire during startup, but they belong to the Spring Framework event model, not the Spring Boot-specific SpringApplicationEvent hierarchy. See Spring Framework Core for more on the standard Spring event model.

Implementation Snippets

Custom SpringApplicationBuilder Configuration

The fluent builder API lets you configure the application before run() is called:

new SpringApplicationBuilder(MyApplication.class)
    .properties("server.port=8080")
    .profiles("production")
    .bannerMode(Banner.Mode.OFF)
    .listeners(new MetricsPublisher())
    .run(args);

This comes in handy in test setups or when you need environment-specific bootstrapping logic in main() before auto-configuration takes over.

Custom Banner Class

Replace the default banner entirely with your own implementation:

@Component
public class CustomBanner implements Banner {

    @Override
    public void printBanner(Environment environment, Class<?> sourceClass, PrintStream out) {
        out.println("========================================");
        out.println("  CUSTOM APPLICATION v" + environment.getProperty("app.version"));
        out.println("========================================");
    }
}

Wire it in by setting it on the SpringApplication instance:

SpringApplication app = new SpringApplication(MyApplication.class);
app.setBanner(new CustomBanner());
app.run(args);

ApplicationListener Implementation

For cleaner separation, use SmartApplicationListener which gives you event-type filtering:

@Component
public class EnvironmentDumper
    implements SmartApplicationListener {

    @Override
    public void onApplicationEvent(ApplicationEnvironmentPreparedEvent event) {
        ConfigurableEnvironment env = event.getEnvironment();
        env.getPropertySources().forEach(ps ->
            System.out.println("PropertySource: " + ps.getName()));
    }

    @Override
    public boolean supportsEventType(Class<? extends ApplicationEvent> eventType) {
        return ApplicationEnvironmentPreparedEvent.class.isAssignableFrom(eventType);
    }

    @Override
    public int getOrder() {
        return Ordered.HIGHEST_PRECEDENCE + 20;
    }
}

SmartApplicationListener gives you supportsEventType() and supportsSourceType() filters, which is more flexible than the raw ApplicationListener interface.

EnvironmentPostProcessor

EnvironmentPostProcessor runs before the ApplicationContext is created. It mutates the ConfigurableEnvironment, adding custom property sources. This is the same mechanism behind built-in support for application.yml and application.properties.

public class MyEnvironmentPostProcessor implements EnvironmentPostProcessor {

    private final YamlPropertySourceLoader loader = new YamlPropertySourceLoader();

    @Override
    public void postProcessEnvironment(
            ConfigurableEnvironment environment,
            SpringApplication application) {

        Resource path = new ClassPathResource("config.yml");
        if (path.exists()) {
            try {
                List<PropertySource<?>> sources = loader.load("custom-yaml", path);
                environment.getPropertySources().addLast(sources.get(0));
            } catch (IOException ex) {
                throw new IllegalStateException("Failed to load config.yml", ex);
            }
        }
    }
}

Register it in META-INF/spring/org.springframework.boot.BootstrapConfiguration (Spring Boot 3.x):

org.springframework.boot.env.EnvironmentPostProcessor=\
  com.example.myapp.MyEnvironmentPostProcessor

Property sources added via addLast() have the lowest precedence, so existing properties win. Use addFirst() when you need your values to override defaults. This trips people up constantly.

Failure Scenarios

Listeners Throwing Exceptions

If an ApplicationListener throws an uncaught exception, the startup sequence stops and a MultiStackTraceException wraps the original error. The ApplicationFailedEvent gets published if the context existed at that point.

@Component
public class BadListener implements ApplicationListener<ApplicationReadyEvent> {
    @Override
    public void onApplicationEvent(ApplicationReadyEvent event) {
        throw new RuntimeException("Listener failed");  // blocks startup
    }
}

Always wrap listener logic in try-catch if the code can fail, or use @Async for non-critical side effects.

Blocking Startup with Long-Running Listeners

Network calls, infinite loops, or blocking I/O inside listeners block the entire startup sequence. The app never reaches ApplicationReadyEvent, and Kubernetes health probes may report the app as dead even though the JVM is still running.

@Component
public class SlowListener implements ApplicationListener<ApplicationReadyEvent> {
    @Override
    public void onApplicationEvent(ApplicationReadyEvent event) {
        // DANGEROUS: blocks startup
        Thread.sleep(30_000);
    }
}

Use @Async with a dedicated thread pool for any listener work that is not strictly part of the startup critical path.

Circular Dependencies During Refresh

If your listener beans have circular dependencies with other @Component beans, the ContextRefreshedEvent phase fails with a BeanCurrentlyInCreationException. This is a Spring Framework issue, but it surfaces during the refresh phase of SpringApplication.run(). Break the cycle with @Lazy on one of the dependencies, or refactor.

Bean Initialization Order

@PostConstruct on listener beans runs during bean initialization, which happens before ContextRefreshedEvent. So a class that both has @PostConstruct and implements ApplicationListener<ContextRefreshedEvent> will see its @PostConstruct callback fire, and then later the event callback fire for the same logical event. Pick one mechanism and stick with it.

Trade-off Table

ApplicationRunner vs CommandLineRunner

Criteria	ApplicationRunner	CommandLineRunner
Argument representation	ApplicationArguments	Raw String[]
Option parsing effort	Zero (built-in API)	Manual string parsing
Named argument support	Yes (–name=value)	No
Multi-value option support	Yes (getOptionValues())	No
Non-option argument handling	Yes (getNonOptionArgs())	Yes (all args)
Framework preference	Modern, recommended	Legacy compatibility

@PostConstruct vs ApplicationListener

Criteria	@PostConstruct	ApplicationListener
Phase	Bean initialization	Event-based (context refresh)
Context availability	Partial (beans created, context not refreshed)	Full (context refreshed)
Exception handling	Fails bean creation	Can block startup (if not caught)
Ordering control	@Order, depends-on	@Order, listener priority
Multiple events	Single callback	Can listen to multiple event types
Testability	Requires context	Can test event firing in isolation
Use case	Simple initialization	Cross-cutting lifecycle reactions

When to Use / When NOT to Use

Reach for ApplicationRunner or CommandLineRunner When

• You need to run initialization code exactly once after the app context is fully refreshed
• You need access to Spring beans for your startup logic
• You want to control execution order across multiple initializers
• The initialization is critical path (must succeed for the app to be considered healthy)

Don’t Reach for ApplicationRunner / CommandLineRunner When

• You only need to configure a single bean (use @PostConstruct or InitializingBean)
• Your logic is purely infrastructural (put it in an @Configuration class instead)
• You need to run code before the context is created (use EnvironmentPostProcessor or SpringApplicationRunListener)
• You need to react to application lifecycle changes beyond “just after startup” (use ApplicationListener)

Reach for ApplicationListener When

• You need to react to a specific lifecycle event (not just “after startup”)
• You want to hook into early bootstrap phases (programmatic registration required)
• You need the same listener to handle multiple different event types
• You are building a framework or library that participates in Spring Boot’s lifecycle

Don’t Reach for ApplicationListener When

• You only need to initialize one bean’s state (use @PostConstruct)
• You need to run code before beans are created (use EnvironmentPostProcessor)
• Your logic is synchronous and can block (consider @Async wrapping)

Observability Checklist

Tracking startup performance helps catch regressions before they hit production. Combine these techniques with Spring Boot Actuator for a full observability picture.

• Record System.nanoTime() when ApplicationStartingEvent fires, then compare against ApplicationReadyEvent.timeTaken for total startup duration
• Inside listeners, capture timestamps at environmentPrepared and contextLoaded phases to build a breakdown
• Micrometer’s Timer in runners exposes startup duration as a metric automatically:

@Component
public class StartupTimerRunner implements ApplicationRunner {

    private final MeterRegistry registry;

    public StartupTimerRunner(MeterRegistry registry) {
        this.registry = registry;
    }

    @Override
    public void run(ApplicationArguments args) {
        registry.timer("startup.total").record(Duration.ofMillis(
            System.currentTimeMillis() - appStartTime));
    }
}

• Emit a custom ApplicationEvent at the end of your runner chain so downstream systems can react
• Add structured log fields (MDC) with bootstrap phase and request ID to correlate logs during startup. See Spring Boot Logging Configuration for MDC setup details.

Security and Compliance Notes

Sensitive Data in Banners

Never put secrets, API keys, or environment-specific information in banner.txt. The banner prints to System.out before logging is fully configured, and many deployment platforms (Cloud Foundry, Heroku) capture console output in dashboards and logs that may be accessible to unauthorized users.

# UNSAFE - do not do this
My App | API_KEY=${API_KEY} | DB_PASSWORD=${DB_PASSWORD}

Even in internal environments, banners that echo environment variables risk accidental exposure in log aggregators.

Environment Variables During Bootstrap

Between ApplicationStartingEvent and ApplicationEnvironmentPreparedEvent, environment variables are already visible to the process. If your listeners log System.getenv() outputs, those values may end up in application logs. Treat the bootstrap phase as security-sensitive: log as little as possible before ApplicationReadyEvent.

Banner Mode in Production

Set spring.main.banner-mode=off in production. A noisy banner adds no value and consumes bandwidth in your log pipeline.

TLS Configuration for Production

If you configure a custom WebServerFactory with SSL, ensure TLS protocols are restricted to modern versions:

@Configuration
public class SslConfig {
    @Bean
    public TomcatServletWebServerFactory tomcatServletWebServerFactory() {
        TomcatServletWebServerFactory factory = new TomcatServletWebServerFactory();
        factory.setSsl(ssl -> ssl
            .setEnabledProtocols("TLSv1.3", "TLSv1.2")
            .setEnabledCipherSuites(Arrays.asList(
                "TLS_AES_256_GCM_SHA384",
                "TLS_AES_128_GCM_SHA256"
            ))
        );
        return factory;
    }
}

Disable fallback to older protocols (TLSv1.0, TLSv1.1) which have known vulnerabilities.

Access Controls for ApplicationListeners

ApplicationListener beans that interact with sensitive resources should declare explicit role requirements or method-level security:

@Component
@Role(BeanDefinition.ROLE_INFRASTRUCTURE)
public class AuditStartupListener implements ApplicationListener<ApplicationReadyEvent> {

    private final AuditService auditService;

    public AuditStartupListener(AuditService auditService) {
        this.auditService = auditService;
    }

    @Override
    @PreAuthorize("hasRole('ADMIN')")
    public void onApplicationEvent(ApplicationReadyEvent event) {
        auditService.recordStartup(event.getTimestamp());
    }
}

Mark infrastructure components with @Role(BeanDefinition.ROLE_INFRASTRUCTURE) to distinguish them from application beans in security reviews.

Audit Logging for Startup Events

For compliance requirements (SOC2, ISO 27001), log startup events with enough detail to reconstruct what happened:

@Component
public class ComplianceStartupListener implements ApplicationListener<ApplicationEnvironmentPreparedEvent> {

    private static final Logger log = LoggerFactory.getLogger(ComplianceStartupListener.class);

    @Override
    public void onApplicationEvent(ApplicationEnvironmentPreparedEvent event) {
        Environment env = event.getEnvironment();
        log.info("STARTUP_AUDIT: environment={}, profiles={}, java_version={}",
            env.getProperty("spring.application.name"),
            String.join(",", env.getActiveProfiles()),
            System.getProperty("java.version")
        );
    }
}

Capture: application name, active profiles, Java version, startup timestamp, and hostname. Do not log secrets or passwords. Store startup logs with appropriate retention for your compliance framework.

Banner Mode Production Settings

Set spring.main.banner-mode=off in production. A noisy banner adds no value and consumes bandwidth in your log pipeline.

Common Pitfalls

@PostConstruct Order: @PostConstruct runs during bean initialization, before ContextRefreshedEvent. A class that combines @PostConstruct with ApplicationListener<ContextRefreshedEvent> gets two callbacks for one logical event. This catches everyone at least once.

Listener Exceptions Blocking Startup: An uncaught exception in any ApplicationListener (except via @Async) halts the entire startup sequence. Wrap risky code:

@Override
public void onApplicationEvent(ContextRefreshedEvent event) {
    try {
        doRiskyThing();
    } catch (Exception ex) {
        logger.error("Startup task failed", ex);
    }
}

Multiple CommandLineRunners with Same @Order: When two runners share the same @Order value, Spring breaks the tie by bean name alphabetically. This is deterministic but surprising. Use unique order values when runners have implicit dependencies.

Listener Registration Timing: A @Bean-scanned listener cannot receive ApplicationStartingEvent or ApplicationEnvironmentPreparedEvent because those fire before the bean factory exists. For early events, use programmatic registration or a BootstrapConfiguration file.

Banner Caching: Spring Boot caches the resolved banner. If you swap banner.txt at runtime for multi-tenant deployments, remember to call app.setBanner() before each run() call or the change won’t take effect in the same JVM session.

EnvironmentPostProcessor Property Source Precedence: addLast() puts your property source at the bottom of the priority chain, so defaults win. If your custom properties are being ignored, check whether you should be using addFirst() instead.

Quick Recap Checklist

• Spring Boot fires events in this order: Starting → EnvironmentPrepared → ContextInitialized → Prepared → Started → Ready
• ApplicationStartingEvent and ApplicationEnvironmentPreparedEvent fire before the bean factory exists; @Bean listeners won’t catch them
• ApplicationRunner beats CommandLineRunner for modern apps because ApplicationArguments handles parsing for you
• Control runner order with @Order — lower numbers run first
• EnvironmentPostProcessor mutates the environment before the context exists; registered in BootstrapConfiguration
• Uncaught listener exceptions halt startup; wrap risky code in try-catch
• @PostConstruct fires before ContextRefreshedEvent on the same bean — don’t mix the two without knowing the order
• Set spring.main.banner-mode=off in production
• Never echo secrets or env vars in banner.txt
• SmartApplicationListener is more expressive than raw ApplicationListener when you need fine-grained event filtering

Interview Questions

Further Reading

• Spring Boot Roadmap — Structured learning path for Spring Boot
• Spring Framework Core — Spring event model fundamentals
• Spring Boot Actuator — Observability and startup endpoint
• Spring Boot Logging Configuration — MDC and structured logging for bootstrap phases
• Spring Boot Banner Documentation — Official banner customization reference
• Spring Boot Application Events Guide — Complete events reference

Conclusion

SpringApplication is the orchestration layer that bootstraps your Spring Boot application, firing events in a predictable sequence that you can hook into at every stage. The key customization points—banners, runners, event listeners, and programmatic configuration via SpringApplicationBuilder—give you control over startup behavior without modifying your application code.

Remember that early events like ApplicationStartingEvent and ApplicationEnvironmentPreparedEvent fire before the bean factory exists, so programmatic registration is required. Use ApplicationRunner over CommandLineRunner for modern argument parsing, and always protect sensitive endpoints exposed during bootstrap. The startup sequence is not just infrastructure—it is the first opportunity to validate your application’s health and readiness.