spring-projects/spring-security · error · IllegalArgumentException

Instead of calling this setter, please call toBuilder to…

Error message

Instead of calling this setter, please call toBuilder to create a new instance

What it means

SimpleAuthentication is an immutable authentication token; its setAuthenticated method deliberately always throws IllegalArgumentException to enforce immutability. Callers must create a new instance via toBuilder() instead of mutating an existing one.

Solutions

1. Use toBuilder() to create a new instance with authenticated=true and store that in the SecurityContext
2. If you need a mutable token, use a mutable Authentication implementation such as UsernamePasswordAuthenticationToken
3. Refactor code that toggles authentication state to construct the token with the correct state up front

Example fix

// before
auth.setAuthenticated(true);
// after
Authentication newAuth = SimpleAuthentication.builder(auth)
    .authenticated(true)
    .build();

if (auth instanceof SimpleAuthentication) { /* immutable: do not call setAuthenticated */ }

boolean isImmutableToken(Authentication a) { return a instanceof SimpleAuthentication; }

When it happens

Trigger: Calling setAuthenticated(true/false) on a SimpleAuthentication instance returned by an API (e.g. an already-authenticated token from the security context).

Common situations: Code that historically mutated UsernamePasswordAuthenticationToken or other mutable tokens being ported to the immutable SimpleAuthentication introduced in recent Spring Security 6.x/7 refactors.

Understand the failure class

Background: "is deprecated and will be removed" — deprecation warnings for old API names, keywords, and options, and how to migrate before the removal release — this error's family across 29 libraries.

Related errors

• AbstractUserDetailsAuthenticationProvider.credentialsExpired
• AbstractUserDetailsAuthenticationProvider.disabled
• AbstractUserDetailsAuthenticationProvider.expired
• AbstractUserDetailsAuthenticationProvider.locked
• AccountStatusUserDetailsChecker.disabled

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

Appendix: source

Thrown at core/src/main/java/org/springframework/security/core/SimpleAuthentication.java:79

	@Override
	public @Nullable Object getDetails() {
		return this.details;
	}

	@Override
	public @Nullable Object getPrincipal() {
		return this.principal;
	}

	@Override
	public boolean isAuthenticated() {
		return this.authenticated;
	}

	@Override
	public void setAuthenticated(boolean isAuthenticated) throws IllegalArgumentException {
		throw new IllegalArgumentException(
				"Instead of calling this setter, please call toBuilder to create a new instance");
	}

	@Override
	public String getName() {
		return (this.principal == null) ? "" : this.principal.toString();
	}

	static final class Builder implements Authentication.Builder<Builder> {

		private final Log logger = LogFactory.getLog(getClass());

		private final Collection<GrantedAuthority> authorities = new LinkedHashSet<>();

		private @Nullable Object principal;

		private @Nullable Object credentials;

View on GitHub (pinned to 96852e8860)