Add UnreachableFilterChainException

config/src/main/java/org/springframework/security/config/annotation/web/builders/WebSecurity.java

@@ -50,6 +50,7 @@
 import org.springframework.security.web.FilterChainProxy.FilterChainDecorator;
 import org.springframework.security.web.FilterInvocation;
 import org.springframework.security.web.SecurityFilterChain;
+import org.springframework.security.web.UnreachableFilterChainException;
 import org.springframework.security.web.access.AuthorizationManagerWebInvocationPrivilegeEvaluator;
 import org.springframework.security.web.access.AuthorizationManagerWebInvocationPrivilegeEvaluator.HttpServletRequestTransformer;
 import org.springframework.security.web.access.DefaultWebInvocationPrivilegeEvaluator;
@@ -309,7 +310,7 @@ protected Filter performBuild() throws Exception {
 				String message = "A filter chain that matches any request [" + anyRequestFilterChain
 						+ "] has already been configured, which means that this filter chain [" + securityFilterChain
 						+ "] will never get invoked. Please use `HttpSecurity#securityMatcher` to ensure that there is only one filter chain configured for 'any request' and that the 'any request' filter chain is published last.";
-				throw new IllegalArgumentException(message);
+				throw new UnreachableFilterChainException(message, securityFilterChain, anyRequestFilterChain);
 			}
 			if (securityFilterChain instanceof DefaultSecurityFilterChain defaultSecurityFilterChain) {
 				if (defaultSecurityFilterChain.getRequestMatcher() instanceof AnyRequestMatcher) {

config/src/test/java/org/springframework/security/config/annotation/web/configuration/WebSecurityConfigurationTests.java

@@ -323,7 +323,7 @@ public void loadConfigWhenTwoSecurityFilterChainsPresentAndSecondWithAnyRequestT
 		assertThatExceptionOfType(BeanCreationException.class)
 			.isThrownBy(() -> this.spring.register(MultipleAnyRequestSecurityFilterChainConfig.class).autowire())
 			.havingRootCause()
-			.isExactlyInstanceOf(IllegalArgumentException.class);
+			.isInstanceOf(IllegalArgumentException.class);
 	}
 
 	private void assertAnotherUserPermission(WebInvocationPrivilegeEvaluator privilegeEvaluator) {

web/src/main/java/org/springframework/security/web/UnreachableFilterChainException.java

@@ -0,0 +1,56 @@
+/*
+ * Copyright 2002-2024 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.security.web;
+
+/**
+ * An exception that describes the configuration error of having placed a more
+ * narrowly-scoped {@link SecurityFilterChain} behind a more broadly-scoped one.
+ *
+ * @author Josh Cummings
+ * @since 6.4
+ */
+public class UnreachableFilterChainException extends IllegalArgumentException {
+
+	private final SecurityFilterChain blocked;
+
+	private final SecurityFilterChain blocker;
+
+	public UnreachableFilterChainException(String message, SecurityFilterChain blocked, SecurityFilterChain blocker) {
+		super(message);
+		this.blocked = blocked;
+		this.blocker = blocker;
+	}
+
+	/**
+	 * The {@link SecurityFilterChain} that is unreachable due to being blocked by the
+	 * {@link #blocker}.
+	 * @return the blocked {@link SecurityFilterChain}
+	 */
+	public SecurityFilterChain getBlocked() {
+		return this.blocked;
+	}
+
+	/**
+	 * The {@link SecurityFilterChain} that is blocking the unreachable
+	 * {@link SecurityFilterChain}.
+	 * @return the blocking {@link SecurityFilterChain}
+	 */
+	public SecurityFilterChain getBlocker() {
+		return this.blocker;
+	}
+
+}