spring-projects/spring-security · error · IllegalStateException

Could not create a default ServerMaximumSessionsExceededHand

Error message

Could not create a default ServerMaximumSessionsExceededHandler. Please provide a ServerMaximumSessionsExceededHandler via DSL

What it means

When session concurrency control is configured, ServerHttpSecurity needs a ServerMaximumSessionsExceededHandler. It tries to build a default from the WebSessionManager's session store (InvalidateLeastUsed...), and if no WebSessionManager bean of the expected type exists and none was supplied via DSL, it throws this IllegalStateException.

Source

Thrown at config/src/main/java/org/springframework/security/config/web/server/ServerHttpSecurity.java:1558

				SessionRegistryWebFilter sessionRegistryWebFilter = new SessionRegistryWebFilter(
						reactiveSessionRegistry);
				configureSuccessHandlerOnAuthenticationFilters();
				http.addFilterAfter(sessionRegistryWebFilter, SecurityWebFiltersOrder.HTTP_HEADERS_WRITER);
			}
		}

		private ServerMaximumSessionsExceededHandler getMaximumSessionsExceededHandler() {
			if (this.maximumSessionsExceededHandler != null) {
				return this.maximumSessionsExceededHandler;
			}
			DefaultWebSessionManager webSessionManager = getBeanOrNull(
					WebHttpHandlerBuilder.WEB_SESSION_MANAGER_BEAN_NAME, DefaultWebSessionManager.class);
			if (webSessionManager != null) {
				this.maximumSessionsExceededHandler = new InvalidateLeastUsedServerMaximumSessionsExceededHandler(
						webSessionManager.getSessionStore());
			}
			if (this.maximumSessionsExceededHandler == null) {
				throw new IllegalStateException(
						"Could not create a default ServerMaximumSessionsExceededHandler. Please provide "
								+ "a ServerMaximumSessionsExceededHandler via DSL");
			}
			return this.maximumSessionsExceededHandler;
		}

		private void configureSuccessHandlerOnAuthenticationFilters() {
			if (ServerHttpSecurity.this.formLogin != null) {
				ServerHttpSecurity.this.formLogin.defaultSuccessHandlers.add(0, this.authenticationSuccessHandler);
			}
			if (ServerHttpSecurity.this.oauth2Login != null) {
				ServerHttpSecurity.this.oauth2Login.defaultSuccessHandlers.add(0, this.authenticationSuccessHandler);
			}
			if (ServerHttpSecurity.this.httpBasic != null) {
				ServerHttpSecurity.this.httpBasic.defaultSuccessHandlers.add(0, this.authenticationSuccessHandler);
			}
		}

View on GitHub (pinned to 96852e8860)

Solutions

1. Provide a ServerMaximumSessionsExceededHandler via the DSL: .sessionManagement(s -> s.maximumSessions(...).maxSessionsExceededHandler(handler))
2. Publish a standard DefaultWebSessionManager bean so the default InvalidateLeastUsedServerMaximumSessionsExceededHandler can be created
3. Ensure the WebSessionManager bean is registered under the expected WebHttpHandlerBuilder.WEB_SESSION_MANAGER_BEAN_NAME

Example fix

// before
http.sessionManagement(s -> s.maximumSessions(SessionLimit.of(1)));

// after
http.sessionManagement(s -> s.maximumSessions(SessionLimit.of(1))
    .maxSessionsExceededHandler(new InvalidateLeastUsedServerMaximumSessionsExceededHandler(sessionStore)));

boolean hasDefaultSource = context.getBeanNamesForType(DefaultWebSessionManager.class).length > 0
    || maxSessionsExceededHandler != null;
if (!hasDefaultSource) {
  throw new IllegalStateException("Provide a ServerMaximumSessionsExceededHandler via DSL or a DefaultWebSessionManager bean");
}

When it happens

Trigger: Using sessionManagement(maximumSessions...) in reactive config while the context lacks a WebSessionManager bean named 'webHttpHandlerBuilder.webSessionManager' (e.g. a custom SessionManager implementation) and no maximumSessionsExceededHandler is set in the DSL.

Common situations: Applications with a custom reactive session management setup (e.g. custom WebSessionManager without a SessionStore); tests with minimal context; switching session stores in a way the default handler factory does not recognize.

Understand the failure class

Background: "X is required", "must be set", "cannot be empty": the missing-required-config error family, from Vertex AI project/location to WeChat keys — this error's family across 18 libraries.

Related errors

• A ReactiveSessionRegistry is needed for concurrent session m
• Cannot apply {configurer} to already built object
• managerPassword is required if managerDn is supplied
• org.springframework.security.config.annotation.method.config
• AdviceMode {adviceMode} is not supported

AI-assisted analysis of spring-projects/spring-security@96852e8860 (2026-09-10). Data as JSON: /api/errors/9bbab40866fa4bb0. Report an issue: GitHub.