What’s New in Spring Boot 3.1? Key Features, Upgrades, and Migration Tips

Spring Boot 3.1.0 has been released, adding a large number of new features and improvements.

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>3.1.0</version>
    <relativePath/> <!-- lookup parent from repository -->
</parent>

Highlights

Automatic configuration for Spring Authorization Server

Support for managing external services with Testcontainers and Docker Compose during development

Simplified Testcontainers configuration in integration tests

Support for Mockito unit testing

Upgrade HttpClient 5

Spring Framework 6 recommends using Apache HttpClient 5, removing support for HttpClient 4 and RestTemplate. Spring Boot 3.0 managed both HttpClient 4 and 5, but using HttpClient 4 can still cause hard‑to‑diagnose errors with RestTemplate. Spring Boot 3.1 removes HttpClient 4 dependency management to encourage migration to HttpClient 5.

Servlet and Filter Registration Optimization

If registration of ServletRegistrationBean or FilterRegistrationBean fails, an IllegalStateException is now thrown instead of a warning. To retain the old behavior, call setIgnoreRegistrationFailure(true) on the bean.

Git Commit ID Maven Plugin Version Property

The property for overriding io.github.git-commit-id:git-commit-id-maven-plugin version has been updated to match its artifact name. Replace git-commit-id-plugin.version with git-commit-id-maven-plugin.version in pom.xml.

Spring Kafka Retry Topic Auto‑Configuration

When spring.kafka.retry.topic.enabled=true and exponential back‑off with a maximum delay is used, all retry attempts now go to the same topic, instead of creating separate topics for each delay level.

Testcontainers Dependency Management

Spring Boot now manages Testcontainers dependencies. The version can be overridden with the testcontainers.version property if needed.

Hibernate 6.2

Spring Boot 3.1 upgrades to Hibernate 6.2. See the Hibernate 6.2 migration guide for potential impact on applications.

Jackson 2.15

Spring Boot 3.1 upgrades to Jackson 2.15. Refer to the Jackson Wiki for changes. Notable changes include stream read constraints; they can be adjusted with a Jackson2ObjectMapperBuilderCustomizer bean:

@Bean
Jackson2ObjectMapperBuilderCustomizer customStreamReadConstraints() {
    return builder -> builder.postConfigurer(objectMapper ->
        objectMapper.getFactory()
            .setStreamReadConstraints(StreamReadConstraints.builder()
                .maxNestingDepth(2000)
                .build()));
}

Upgrade Mockito 5

Spring Boot 3.1 upgrades to Mockito 5 (specifically 5.3). See the Mockito release notes for significant changes in the 5.x series.

Health Groups Default Validation

Health group members are now validated at startup. If a health indicator is included or excluded but does not exist, the application fails to start. Set management.endpoint.health.validate-group-membership=false to disable this validation and revert to earlier behavior.

Service Connections

A new Service Connection concept is introduced via ConnectionDetails beans, which provide the necessary details to establish connections to remote services. Spring Boot’s auto‑configuration now consumes these beans, giving them priority over related configuration properties. Connection‑related properties that are unrelated to the connection itself (e.g., pool size) continue to be used.

Docker Compose

The new module spring-boot-docker-compose integrates Docker Compose. At startup, it looks for configuration files in the current working directory, supporting compose.yaml, compose.yml, docker-compose.yaml, and docker-compose.yml. Non‑standard file names can be specified with spring.docker.compose.file. Declared services are started with docker-compose up, and their connection details are added as beans. On shutdown, docker-compose down is executed. Lifecycle behavior can be customized with properties such as spring.docker.compose.lifecycle-management, spring.docker.compose.startup.command, and spring.docker.compose.shutdown.command. See the reference documentation for supported services.

SSL Configuration

SSL trust material (Java KeyStores, PEM‑encoded certificates) can now be configured via properties and applied consistently across embedded web servers, data services, RestTemplate, and WebClient. See the reference documentation for details.

Spring Authorization Server Auto‑Configuration

This release adds support for Spring Authorization Server with a new starter spring-boot-starter-oauth2-authorization-server. Refer to the Authorization Server section of the Spring Boot reference documentation for more information.

Docker Image Build

Image Creation Date and Time

The spring-boot:build-image Maven goal and bootBuildImage Gradle task now have a createdDate option, allowing the image metadata’s Created field to be set to a user‑specified date or now for the current timestamp. See the Gradle and Maven plugin documentation.

Image Application Directory

The same build tasks also have an applicationDirectory option, which defines where application content is uploaded inside the builder image before the package is consumed, and where it will reside in the resulting image. See the Gradle and Maven plugin documentation.