spring-projects/spring-security · error · IllegalStateException

Could not create a default…

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.

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…
• A filter chain that matches any request
• A ServerOneTimeTokenGenerationSuccessHandler is required to…
• AdviceMode is not supported
• An error occurred while attempting to decode the Jwt: +…

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

Appendix: 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)