SpringBoot version conflicts result in NoSuchFieldError solution

1. Problem background

In Spring Boot multi-module project, if the parent module and the child module refer to different versions of Spring Boot dependencies (for example, the parent module uses 2.7.3 and the child module uses 3.2.1), the following error may occur at runtime:

: ESCAPE_CHARACTER
    at .<init>(:51)
    ...

This error is usuallyDependency version incompatibleorClasspath pollutionThis requires systematic investigation and version management to solve the problem.

2. Analysis of the cause of the problem

1. Spring Boot version is incompatible

• The core differences between Spring Boot and：
  • Package name migration: Spring Boot is based on Jakarta EE 9+, the package name is fromjavax.*Migrate tojakarta.*(like → ）。
  • JDK version requirements: Spring Boot requires Java 17+ and supports Java 8+.
  • API changes: Some classes or methods are removed or renamed (e.g.ESCAPE_CHARACTERFields may not exist in Spring Boot).

2. The root of dependency conflict

• Multi-module version inconsistent: Parent module and child module explicitly declare different Spring Boot versions, resulting in confusion in dependency tree.
• Transmitted dependency pollution: Third-party libraries may implicitly rely on older versions of Spring Boot, overwriting the version declaration of the parent module.

3. Solution

1. Unified Spring Boot Version

Step 1: Select the target version

• Solution A (recommended): Upgrade to Spring Boot 3.2.1
  Make sure the project is compatible with Java 17+ and handles package name migration (e.g.javax → jakarta）。
• Solution B: Downgrade submodule to 2.7.3
  Remove explicit references to 3.2.1 in the submodule and inherit the parent module version.

Step 2: Configure the parent module's

<!-- Parent module -->
<parent>
    <groupId></groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>3.2.1</version> <!-- Unified version -->
    <relativePath/>
</parent>

<properties>
    <>17</> <!-- Java 17+ for Spring Boot  -->
</properties>

<!-- useBOMManage dependency versions（recommend） -->
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId></groupId>
            <artifactId>spring-cloud-dependencies</artifactId>
            <version>2022.0.8</version> <!-- correspondSpring Boot 3.2 -->
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

Step 3: Submodule inherits parent module

<!-- Submodules -->
<parent>
    <groupId></groupId>
    <artifactId>parent-module</artifactId>
    <version>1.0.0</version>
    <relativePath>../</relativePath> <!-- Point to parent module -->
</parent>

<dependencies>
    <dependency>
        <groupId></groupId>
        <artifactId>spring-boot-starter-web</artifactId>
        <!-- No need to specifyversion，Managed by the parent module -->
    </dependency>
    <!-- Other dependencies -->
</dependencies>

2. Eliminate conflict dependencies

If the third-party library introduces the old version of Spring Boot, it needs to be explicitly excluded:

<!-- Submodules -->
<dependency>
    <groupId></groupId>
    <artifactId>third-party-lib</artifactId>
    <version>1.0.0</version>
    <exclusions>
        <exclusion>
            <groupId></groupId>
            <artifactId>spring-boot</artifactId>
        </exclusion>
    </exclusions>
</dependency>

3. Use Maven/Gradle tools to troubleshoot dependencies

Maven dependency tree analysis

mvn dependency:tree -Dincludes=

Gradle dependency tree analysis

gradle dependencies --configuration compileClasspath | grep ''

Using the Maven Helper Plugin (IDEA)

• Install plug-in:Maven Helper。
• Right-click → Maven Helper → Show Dependencies, highlight conflict items in red.

4. Advanced tips for Spring Boot migration

Package name migration example

// Spring Boot （javax）
import ;

// Spring Boot （jakarta）
import ;

Bulk replacement package name (Maven)

<!-- Medium configurationreplacerPlugin -->
<build>
    <plugins>
        <plugin>
            <groupId>-replacer-plugin</groupId>
            <artifactId>replacer</artifactId>
            <version>1.5.4</version>
            <configuration>
                <includes>
                    <include>**/*.java</include>
                </includes>
                <replacements>
                    <replacement>
                        <token></token>
                        <value></value>
                    </replacement>
                </replacements>
            </configuration>
        </plugin>
    </plugins>
</build>

AOT compilation optimization startup speed

<!-- Enabled inAOTCompilation -->
<plugin>
    <groupId></groupId>
    <artifactId>spring-boot-maven-plugin</artifactId>
    <configuration>
        <compilerPlugins>
            <plugin>aot</plugin>
        </compilerPlugins>
    </configuration>
</plugin>

4. FAQ

Q1: How to quickly detect Spring Boot version conflicts?

• Maven:runmvn dependency:tree, find different versions of Spring Boot dependencies.
• Gradle:run./gradlew dependencies,searchversion differences.
• IDEA: Use the Maven Helper plugin to view dependency conflicts intuitively.

Q2: What should I do if the project needs to use Spring Boot and at the same time?

• Not recommended: Spring Boot and APIs are quite different, and mixed use may lead to unpredictable errors.
• Solution：
  1. Independent modules: Split different versions of the code into independent projects.
  2. Isolated Class Loader: Isolated via OSGi or custom class loader, but with high complexity.

Q3: How to unify the version in Gradle project?

// （Kotlin DSL）
plugins {
    id("") version "3.2.1" apply false
    id("-management") version "1.1.4"
}

dependencyManagement {
    imports {
        mavenBom(":spring-cloud-dependencies:2022.0.8")
    }
}

// Submodule inheritance configurationdependencies {
    implementation(":spring-boot-starter-web")
}

Q4: What should I do if I encounter NoClassDefFoundError during the migration process?

• reason: Dependencies are not correctly excluded or version mismatched.
• Solution steps：
  1. Check the dependency tree:mvn dependency:tree。
  2. Exclude conflict dependencies (such as the older version of Spring Boot).
  3. Ensure that all third-party libraries are compatible with the target Spring Boot version.

Q5: How to deal with Spring Boot compatibility issues with legacy libraries?

• plan：
  1. Upgrade legacy library: Select a version that supports Jakarta EE (such as Hibernate).
  2. Adaptation layer: Compatible with old APIs through wrapper class or adapter mode.
  3. Isolation module: Split the legacy functions into independent modules, using Spring Boot.

Q6: How to avoid dependency version fallback?

• Maven Enforcer Plugin: Force checking dependent version:

<plugin>
    <groupId></groupId>
    <artifactId>maven-enforcer-plugin</artifactId>
    <version>3.1.0</version>
    <executions>
        <execution>
            <goals>
                <goal>enforce</goal>
            </goals>
            <configuration>
                <rules>
                    <requireUpperBoundDeps/>
                    <bannedDependencies>
                        <searchTransitive>true</searchTransitive>
                        <excludes>
                            <exclude>:spring-boot:2.7.3</exclude>
                        </excludes>
                    </bannedDependencies>
                </rules>
            </configuration>
        </execution>
    </executions>
</plugin>

Q7: How to choose the Spring Cloud version of Spring Boot?

• Spring Cloud 2022.Corresponding to Spring Boot 3.
• Spring Cloud 2023.Corresponding to Spring Boot 3.

<!-- Parent module -->
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId></groupId>
            <artifactId>spring-cloud-dependencies</artifactId>
            <version>2023.0.0</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

Q8: How to quickly verify Spring Boot version?

• Print version in code：

@SpringBootApplication
public class Application {
    public static void main(String[] args) {
        ("Spring Boot Version: " + ());
        (, args);
    }
}

Q9: Dependency conflict causes startup failure. How to quickly locate it?

• Enable detailed logging:existAdded in:

=DEBUG

• Check the class loading path:passofgetProtectionDomain()Methods locate the source of conflicting classes.

Q10: How to adapt the database driver of Spring Boot?

• MySQL driver:usemysql:mysql-connector-jReplace the old versionmysql-connector-java。
• PostgreSQL: Upgrade to:postgresql:42.6.0and above.

5. Summary

Spring Boot version conflict is a common problem in multi-module projects and needs to be resolved through the following steps:

1. Unified version: Manage dependent versions through parent module.
2. Eliminate pollution: Explicitly exclude conflicting dependencies from third-party libraries.
3. Tool Assistance: Use Maven Helper ordependency:treeTroubleshoot conflicts.
4. Migration adaptation: If you upgrade to Spring Boot, you need to handle package name, JDK version and third-party library compatibility.

The above is the detailed content of the solution to the SpringBoot version conflict that causes NoSuchFieldError. For more information about SpringBoot version conflict NoSuchFieldError, please follow my other related articles!