spring-projects/spring-security · error · PreAuthenticatedCredentialsNotFoundException

${principalEnvironmentVariable} variable not found in reques

Error message

${principalEnvironmentVariable} variable not found in request.

What it means

RequestAttributeAuthenticationFilter.getPreAuthenticatedPrincipal() extracts the user identity from an HttpServletRequest attribute named by principalEnvironmentVariable. When the attribute is absent it throws PreAuthenticatedCredentialsNotFoundException (a subclass of AuthenticationException) so the failure can be handled by the standard authentication-failure flow, but only if exceptionIfVariableMissing is true; otherwise it returns null.

Source

Thrown at web/src/main/java/org/springframework/security/web/authentication/preauth/RequestAttributeAuthenticationFilter.java:64

public class RequestAttributeAuthenticationFilter extends AbstractPreAuthenticatedProcessingFilter {

	private String principalEnvironmentVariable = "REMOTE_USER";

	private @Nullable String credentialsEnvironmentVariable;

	private boolean exceptionIfVariableMissing = true;

	/**
	 * Read and returns the variable named by {@code principalEnvironmentVariable} from
	 * the request.
	 * @throws PreAuthenticatedCredentialsNotFoundException if the environment variable is
	 * missing and {@code exceptionIfVariableMissing} is set to {@code true}.
	 */
	@Override
	protected @Nullable Object getPreAuthenticatedPrincipal(HttpServletRequest request) {
		String principal = (String) request.getAttribute(this.principalEnvironmentVariable);
		if (principal == null && this.exceptionIfVariableMissing) {
			throw new PreAuthenticatedCredentialsNotFoundException(
					this.principalEnvironmentVariable + " variable not found in request.");
		}
		return principal;
	}

	/**
	 * Credentials aren't usually applicable, but if a
	 * {@code credentialsEnvironmentVariable} is set, this will be read and used as the
	 * credentials value. Otherwise a dummy value will be used.
	 */
	@Override
	protected @Nullable Object getPreAuthenticatedCredentials(HttpServletRequest request) {
		if (this.credentialsEnvironmentVariable != null) {
			return request.getAttribute(this.credentialsEnvironmentVariable);
		}
		return "N/A";
	}

View on GitHub (pinned to 96852e8860)

Solutions

1. Ensure the attribute is set before this filter runs: check filter order and that the component setting request.setAttribute(principalEnvironmentVariable, ...) is in the chain.
2. Verify principalEnvironmentVariable (setPrincipalEnvironmentVariable) exactly matches the attribute name set upstream.
3. Call setExceptionIfVariableMissing(false) if requests without the attribute should be handled by other auth mechanisms instead of failing.
4. Add debug logging on the request before the filter to confirm which attributes are actually present.
5. Protect the app behind the SSO gateway so it cannot receive direct traffic lacking the attribute.

Example fix

// before
<bean class="org.springframework.security.web.authentication.preauth.RequestAttributeAuthenticationFilter">
  <property name="principalEnvironmentVariable" value="remote_user"/>
  <property name="exceptionIfVariableMissing" value="true"/>
</bean>
// after
<bean class="org.springframework.security.web.authentication.preauth.RequestAttributeAuthenticationFilter">
  <property name="principalEnvironmentVariable" value="j_username"/> <!-- matches attribute set by SSO filter -->
  <property name="exceptionIfVariableMissing" value="false"/>
</bean>

if (request.getAttribute(principalEnvironmentVariable) == null) {
    throw new PreAuthenticatedCredentialsNotFoundException(principalEnvironmentVariable + " variable not found in request.");
}

try {
    filter.doFilter(request, response, chain);
} catch (PreAuthenticatedCredentialsNotFoundException e) {
    logger.warn("Pre-auth attribute missing", e);
    response.sendError(HttpServletResponse.SC_FORBIDDEN);
}

When it happens

Trigger: RequestAttributeAuthenticationFilter is configured with setExceptionIfVariableMissing(true) and a request arrives whose attribute (principalEnvironmentVariable, e.g. 'j_username' or a custom name) has never been set by an upstream filter, servlet or gateway.

Common situations: The upstream component expected to set the request attribute (often an SSO agent or another filter in the chain) is missing from the filter chain or ordered after this filter; attribute name mismatch after a rename/config change; direct access to the app bypassing the SSO gateway that sets the attribute.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• ${principalRequestHeader} header not found in request.
• No pre-authenticated principal found in request.
• No pre-authenticated credentials found in request.
• Access is denied
• RunAsImplAuthenticationProvider.incorrectKey

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