{"record":{"id":"ba21c587f5b0dcef","repo":"spring-projects/spring-security","slug":"principalenvironmentvariable-variable-not-found","errorCode":null,"errorMessage":"${principalEnvironmentVariable} variable not found in request.","messagePattern":"(.+?) variable not found in request\\.","errorType":"exception","errorClass":"PreAuthenticatedCredentialsNotFoundException","httpStatus":null,"severity":"error","filePath":"web/src/main/java/org/springframework/security/web/authentication/preauth/RequestAttributeAuthenticationFilter.java","lineNumber":64,"sourceCode":"public class RequestAttributeAuthenticationFilter extends AbstractPreAuthenticatedProcessingFilter {\n\n\tprivate String principalEnvironmentVariable = \"REMOTE_USER\";\n\n\tprivate @Nullable String credentialsEnvironmentVariable;\n\n\tprivate boolean exceptionIfVariableMissing = true;\n\n\t/**\n\t * Read and returns the variable named by {@code principalEnvironmentVariable} from\n\t * the request.\n\t * @throws PreAuthenticatedCredentialsNotFoundException if the environment variable is\n\t * missing and {@code exceptionIfVariableMissing} is set to {@code true}.\n\t */\n\t@Override\n\tprotected @Nullable Object getPreAuthenticatedPrincipal(HttpServletRequest request) {\n\t\tString principal = (String) request.getAttribute(this.principalEnvironmentVariable);\n\t\tif (principal == null && this.exceptionIfVariableMissing) {\n\t\t\tthrow new PreAuthenticatedCredentialsNotFoundException(\n\t\t\t\t\tthis.principalEnvironmentVariable + \" variable not found in request.\");\n\t\t}\n\t\treturn principal;\n\t}\n\n\t/**\n\t * Credentials aren't usually applicable, but if a\n\t * {@code credentialsEnvironmentVariable} is set, this will be read and used as the\n\t * credentials value. Otherwise a dummy value will be used.\n\t */\n\t@Override\n\tprotected @Nullable Object getPreAuthenticatedCredentials(HttpServletRequest request) {\n\t\tif (this.credentialsEnvironmentVariable != null) {\n\t\t\treturn request.getAttribute(this.credentialsEnvironmentVariable);\n\t\t}\n\t\treturn \"N/A\";\n\t}\n","sourceCodeStart":46,"sourceCodeEnd":82,"githubUrl":"https://github.com/spring-projects/spring-security/blob/96852e8860138a482cb13d1479573f24ff6443c6/web/src/main/java/org/springframework/security/web/authentication/preauth/RequestAttributeAuthenticationFilter.java#L46-L82","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Ensure the attribute is set before this filter runs: check filter order and that the component setting request.setAttribute(principalEnvironmentVariable, ...) is in the chain.","Verify principalEnvironmentVariable (setPrincipalEnvironmentVariable) exactly matches the attribute name set upstream.","Call setExceptionIfVariableMissing(false) if requests without the attribute should be handled by other auth mechanisms instead of failing.","Add debug logging on the request before the filter to confirm which attributes are actually present.","Protect the app behind the SSO gateway so it cannot receive direct traffic lacking the attribute."],"exampleFix":"// before\n<bean class=\"org.springframework.security.web.authentication.preauth.RequestAttributeAuthenticationFilter\">\n  <property name=\"principalEnvironmentVariable\" value=\"remote_user\"/>\n  <property name=\"exceptionIfVariableMissing\" value=\"true\"/>\n</bean>\n// after\n<bean class=\"org.springframework.security.web.authentication.preauth.RequestAttributeAuthenticationFilter\">\n  <property name=\"principalEnvironmentVariable\" value=\"j_username\"/> <!-- matches attribute set by SSO filter -->\n  <property name=\"exceptionIfVariableMissing\" value=\"false\"/>\n</bean>","handlingStrategy":"try-catch","validationCode":"if (request.getAttribute(principalEnvironmentVariable) == null) {\n    throw new PreAuthenticatedCredentialsNotFoundException(principalEnvironmentVariable + \" variable not found in request.\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    filter.doFilter(request, response, chain);\n} catch (PreAuthenticatedCredentialsNotFoundException e) {\n    logger.warn(\"Pre-auth attribute missing\", e);\n    response.sendError(HttpServletResponse.SC_FORBIDDEN);\n}","preventionTips":["Check filter ordering so the attribute-setting component runs before RequestAttributeAuthenticationFilter","Set exceptionIfVariableMissing=false only when another auth mechanism covers attribute-less requests","Route app traffic exclusively through the gateway that sets the attribute"],"tags":["spring-security","preauth","request-attribute","sso"],"backgroundTag":"missing-required-argument","analyzedSha":"96852e8860138a482cb13d1479573f24ff6443c6","analyzedAt":"2026-09-10T23:25:23.477Z","contentChangedAt":"2026-09-10T23:25:23.477Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}