Introduction

A duplicated httpSessionManager bean error in Spring Boot 2.1 with Keycloak usually means two configuration paths are trying to register the same bean name. Spring Boot 2.1 also tightened default behavior around bean overriding, so setups that worked in older versions can fail at startup. The fix is to choose one ownership model for security beans and remove or rename the duplicate registration.

Why This Error Appears

The startup failure normally happens when both Keycloak adapter configuration and custom security configuration declare overlapping beans. In earlier projects, bean overriding might have hidden this issue. In Boot 2.1, duplicate names fail fast unless overriding is explicitly allowed.

Typical symptoms include:

• BeanDefinitionOverrideException
• Startup log mentions httpSessionManager
• Application context stops before web server is ready

Reproduce the Conflict in a Small Example

The following configuration shows the pattern that causes trouble.

1@Configuration
2class KeycloakConfigA {
3    @Bean
4    public HttpSessionManager httpSessionManager() {
5        return new HttpSessionManager();
6    }
7}
8
9@Configuration
10class KeycloakConfigB {
11    @Bean
12    public HttpSessionManager httpSessionManager() {
13        return new HttpSessionManager();
14    }
15}

With this setup, Boot 2.1 will fail because both beans use the same name.

Preferred Fix: One Bean Owner

Keep exactly one httpSessionManager bean definition. If Keycloak auto-configuration already provides it, remove your local duplicate. If you need custom behavior, define your own bean and disable the conflicting auto path.

A safe explicit approach is:

1@Configuration
2class SecurityConfig {
3    @Bean(name = "httpSessionManager")
4    public HttpSessionManager keycloakSessionManager() {
5        HttpSessionManager manager = new HttpSessionManager();
6        return manager;
7    }
8}

Then ensure no second configuration class declares the same bean name.

Temporary Escape Hatch

You can allow bean overriding, but this should be a short-term migration step, not a permanent fix.

spring.main.allow-bean-definition-overriding=true

Use this only while auditing configuration ownership. Silent overriding can hide security misconfiguration, especially in authentication flows.

Align Library Versions

Many failures come from incompatible adapter and framework versions. Keep Keycloak Spring adapter and Spring Boot versions aligned with the adapter compatibility matrix for your dependency set.

A minimal Maven example:

1<dependencies>
2  <dependency>
3    <groupId>org.keycloak</groupId>
4    <artifactId>keycloak-spring-boot-starter</artifactId>
5    <version>6.0.1</version>
6  </dependency>
7  <dependency>
8    <groupId>org.springframework.boot</groupId>
9    <artifactId>spring-boot-starter-security</artifactId>
10  </dependency>
11</dependencies>

Version pinning keeps transitive security classes predictable across environments.

Diagnostic Workflow That Saves Time

Use a startup checklist:

• Search codebase for httpSessionManager bean definitions
• Inspect imported security config classes
• Check active Spring profiles for duplicate config loading
• Print auto-configuration report for conflicting paths
• Verify dependency tree for multiple Keycloak adapter versions

Command example:

mvn -q dependency:tree | grep -i keycloak

If you find two adapter versions, resolve that before deeper debugging.

Modernization Note

For long-term maintenance, many teams migrate away from legacy Keycloak adapters and implement OAuth2 resource server and client flows with Spring Security first-class support. This reduces custom adapter interactions and startup conflicts. Even if migration is not immediate, isolating Keycloak integration behind one configuration module will reduce repeated bean registration issues.

Common Pitfalls

• Defining httpSessionManager in multiple @Configuration classes
• Enabling override permanently and masking real startup conflicts
• Mixing incompatible Keycloak and Spring Boot versions
• Loading duplicate config through profile-specific imports
• Debugging only logs without checking dependency tree and bean names

The issue is usually deterministic once bean ownership is made explicit.

Summary

• Boot 2.1 fails fast when two beans share the same name.
• Duplicate httpSessionManager registrations are the primary cause.
• Keep one bean owner and remove or rename duplicates.
• Use override mode only as a temporary migration tool.
• Validate versions and dependency tree to prevent recurring conflicts.