spring-projects/spring-security · error · IllegalStateException

A ServerOneTimeTokenGenerationSuccessHandler is required to

Error message

A ServerOneTimeTokenGenerationSuccessHandler is required to enable oneTimeTokenLogin(). Please provide it as a bean or pass it to the oneTimeTokenLogin() DSL.

What it means

Enabling oneTimeTokenLogin() on reactive ServerHttpSecurity requires a ServerOneTimeTokenGenerationSuccessHandler to deliver the generated token (e.g. by email/link). If none is provided via the DSL or found as a bean, this IllegalStateException is thrown during filter chain setup.

Source

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

		 * {@link WebSessionServerSecurityContextRepository}. For the
		 * {@code SecurityContext} to be loaded on subsequent requests the
		 * {@link ReactorContextWebFilter} must be configured to be able to load the value
		 * (they are not implicitly linked).
		 * @param securityContextRepository the repository to use
		 * @return the {@link OneTimeTokenLoginSpec} to continue configuring
		 */
		public OneTimeTokenLoginSpec securityContextRepository(
				ServerSecurityContextRepository securityContextRepository) {
			this.securityContextRepository = securityContextRepository;
			return this;
		}

		private ServerOneTimeTokenGenerationSuccessHandler getTokenGenerationSuccessHandler() {
			if (this.tokenGenerationSuccessHandler == null) {
				this.tokenGenerationSuccessHandler = getBeanOrNull(ServerOneTimeTokenGenerationSuccessHandler.class);
			}
			if (this.tokenGenerationSuccessHandler == null) {
				throw new IllegalStateException("""
						A ServerOneTimeTokenGenerationSuccessHandler is required to enable oneTimeTokenLogin().
						Please provide it as a bean or pass it to the oneTimeTokenLogin() DSL.
						""");
			}
			return this.tokenGenerationSuccessHandler;
		}

		/**
		 * Specifies the URL to send users to if login is required. A default login page
		 * will be generated when this attribute is not specified.
		 * @param loginPage the URL to send users to if login is required
		 * @return the {@link OAuth2LoginSpec} for further configuration
		 * @since 6.5
		 */
		public OneTimeTokenLoginSpec loginPage(String loginPage) {
			Assert.hasText(loginPage, "loginPage cannot be empty");
			this.loginPage = loginPage;
			return this;

View on GitHub (pinned to 96852e8860)

Solutions

Publish a ServerOneTimeTokenGenerationSuccessHandler bean implementing token delivery
Pass a handler to the DSL: .oneTimeTokenLogin(ott -> ott.tokenGenerationSuccessHandler(handler))
If one-time token login is not intended, remove the oneTimeTokenLogin() call

Example fix

// before
http.oneTimeTokenLogin();

// after
@Bean
ServerOneTimeTokenGenerationSuccessHandler tokenHandler() {
  return (token, request, response) -> { /* deliver token, e.g. via email */ };
}
http.oneTimeTokenLogin(ott -> ott.tokenGenerationSuccessHandler(tokenHandler()));

Defensive patterns

Strategy: validation

Validate before calling

if (context.getBeanNamesForType(ServerOneTimeTokenGenerationSuccessHandler.class).length == 0) {
  throw new IllegalStateException("oneTimeTokenLogin() requires a ServerOneTimeTokenGenerationSuccessHandler bean");
}

Prevention

Publish the token generation success handler before enabling oneTimeTokenLogin()
Pass the handler explicitly via the DSL instead of bean lookup
Document the required bean next to the security config

When it happens

Trigger: Calling http.oneTimeTokenLogin() in reactive config while neither a ServerOneTimeTokenGenerationSuccessHandler bean exists nor one was passed to the DSL.

Common situations: Adopting magic-link/one-time-token login and assuming a default delivery mechanism exists; upgrading Spring Security and enabling ott login without porting the token generation handler.

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

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