Introduction

This error usually appears when a servlet container scans web-fragment.xml files from dependencies and finds two fragments with the same declared name. In practice, the most common cause is duplicate or conflicting versions of spring-web on the application classpath.

What a Web Fragment Is

In Servlet 3.x applications, JAR files can contribute web configuration through META-INF/web-fragment.xml. Each fragment can declare a name and relative ordering rules.

That only works if fragment names are unique. If the container sees two fragments both named spring_web, it cannot apply relative ordering safely, so startup fails.

This is why the message mentions "not legal with relative ordering." The failure is not about your controller code. It is about dependency packaging.

The Real Root Cause

Most of the time, one of these is true:

• two versions of spring-web are pulled in transitively
• a JAR is bundled twice, once directly and once through another dependency
• an application server already provides a copy and the application ships another

The fix is to clean up the dependency graph, not to add random XML.

Find the Duplicate

On Maven:

mvn dependency:tree | grep spring-web

On Gradle:

./gradlew dependencies --configuration runtimeClasspath | grep spring-web

You are looking for more than one path that contributes spring-web or another JAR containing the same fragment name.

If the application is deployed to a container with shared libraries, also inspect the server's library directory. Sometimes the duplicate is not in your build file at all.

Example Maven Fix

Suppose library-a brings in an older Spring version transitively. Exclude it and keep only one version:

1<dependency>
2  <groupId>com.example</groupId>
3  <artifactId>library-a</artifactId>
4  <version>1.2.3</version>
5  <exclusions>
6    <exclusion>
7      <groupId>org.springframework</groupId>
8      <artifactId>spring-web</artifactId>
9    </exclusion>
10  </exclusions>
11</dependency>
12
13<dependency>
14  <groupId>org.springframework</groupId>
15  <artifactId>spring-web</artifactId>
16  <version>5.3.39</version>
17</dependency>

The exact version is up to the project, but the rule is simple: one coordinated Spring version set, not a mixture.

Why Editing web.xml Is Usually the Wrong First Move

Developers sometimes try to suppress the error by changing web-ordering settings or copying fragment files around. That usually treats the symptom, not the cause.

If the classpath contains duplicate framework JARs, startup may still be unstable even if you silence this particular error. The correct fix is dependency hygiene.

If You Use Spring Boot

In Boot applications packaged as executable JARs, you are less likely to deal with manual fragment ordering directly, but duplicate dependencies can still happen. Use dependency management and avoid overriding core Spring versions casually unless you understand the full version alignment.

Boot's dependency management exists for a reason: the Spring modules are meant to move together.

Common Pitfalls

The biggest mistake is assuming the problem is in application source code. It is usually a packaging problem.

Another mistake is keeping both spring-web and an old shaded or container-provided copy. That can trigger fragment duplication and later classloading issues.

A third issue is fixing one duplicate JAR but leaving the rest of the Spring stack split across incompatible versions. If you touch one Spring dependency manually, inspect the whole family.

Summary

• The error means the servlet container found duplicate web fragments with the same name.
• The usual cause is duplicate or conflicting spring-web JARs on the runtime classpath.
• Use Maven or Gradle dependency inspection to find the duplicate path.
• Prefer fixing dependency alignment over editing fragment ordering by hand.
• Keep Spring modules on one coherent version line to avoid repeat startup failures.