Skip to content
BSWEN
Blog

How to Fix Spring Boot Spring Cloud Version Mismatch NoClassDefFoundError

Cowrie
Cowrie
Dev @ Bswen

The Problem

I was starting a Spring Boot application with Spring Cloud Feign, and I got this error immediately:

Stack trace
java.lang.NoClassDefFoundError: org/springframework/cloud/context/named/NamedContextFactory$Specification
    at org.springframework.cloud.netflix.feign.FeignClientsRegistrar.registerClientConfiguration
    at org.springframework.cloud.netflix.feign.FeignClientsRegistrar.registerFeignClients
    at org.springframework.cloud.netflix.feign.FeignClientsRegistrar.registerBeanDefinitions
    ...
Caused by: java.lang.ClassNotFoundException: org.springframework.cloud.context.named.NamedContextFactory$Specification

The application failed to start before any of my code ran. I had no idea what was happening.

Environment

  • Spring Boot: 1.5.2.RELEASE
  • Spring Cloud: Camden.SR4 (or Camden.SR5, depending on when you hit this)
  • Java: 1.8
  • Maven: 3.x

What I Tried First

I searched for the class name NamedContextFactory$Specification in Google and found it’s part of Spring Cloud Commons. I checked my dependencies and everything looked fine - Spring Cloud Camden was supposed to work with Boot 1.5.x, right?

pom.xml (my initial config)
<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>1.5.2.RELEASE</version>
</parent>


<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.springframework.cloud</groupId>
            <artifactId>spring-cloud-dependencies</artifactId>
            <version>Camden.SR4</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

I tried cleaning and rebuilding:

Maven clean build
mvn clean install

But the error persisted. The class was simply not found at runtime.

The Root Cause

After digging into Stack Overflow and Spring Cloud release notes, I discovered the real problem:

Camden.SR4 does NOT support Spring Boot 1.5.x

The compatibility is much more specific than I thought:

Spring Cloud Camden compatibility
Camden.SR1 to SR4  -> Spring Boot 1.4.x ONLY
Camden.SR5+       -> Spring Boot 1.5.x support added

Spring Boot 1.5.x introduced API changes that broke compatibility with older Camden releases. The NamedContextFactory$Specification class was added or modified in Spring Cloud Commons, and Camden.SR4’s Feign module expected an older version of Spring Cloud Commons that didn’t have this class signature.

This is a runtime class loading failure - Maven won’t catch it at compile time because the dependency versions are technically valid, just incompatible internally.

The Solution

Step 1: Check the Official Compatibility Matrix

Spring provides a compatibility matrix at spring.io. Here’s the general mapping:

Spring Boot / Spring Cloud version mapping
Spring Boot 1.4.x -> Camden, Brixton.SR6
Spring Boot 1.5.x -> Camden.SR5+, Edgware, Dalston
Spring Boot 2.2.x -> Hoxton
Spring Boot 2.4.x -> 2020.0.x (Ilford)
Spring Boot 3.2.x -> 2023.0.x (Leyton)

Step 2: Update Your Spring Cloud Version

For my case with Boot 1.5.2.RELEASE, I needed Camden.SR5 or newer:

pom.xml (correct config)
<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>1.5.2.RELEASE</version>
</parent>


<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.springframework.cloud</groupId>
            <artifactId>spring-cloud-dependencies</artifactId>
            <version>Camden.SR5</version> <!-- SR5+ supports Boot 1.5.x -->
            <!-- Alternative: Edgware.RELEASE or Dalston.RELEASE -->
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

Step 3: Verify with Spring Initializr API

You can programmatically check compatibility using Spring Initializr’s info endpoint:

Check Spring Cloud compatibility
curl -s https://start.spring.io/actuator/info | jq '.spring-cloud'

Output example:

Compatibility ranges
{
  "Hoxton.SR12": "Spring Boot >=2.2.0.RELEASE and <2.4.0.M1",
  "2020.0.0": "Spring Boot >=2.4.0.M1 and <2.5.0.M1"
}

This shows exact version ranges - very helpful when you’re uncertain.

Step 4: Clean and Rebuild

After updating the version, always clean build:

Clean rebuild after version fix
mvn clean install -U

The -U flag forces Maven to update snapshots and releases.

Why This Matters

Version mismatches are particularly dangerous with Spring Cloud because:

  1. Runtime failures - Not caught at compile time
  2. Microservices impact - Feign, Eureka, Config Server all depend on correct versions
  3. Production risk - The app starts fine with mismatched versions in dev but fails when deployed
  4. Debugging confusion - Stack traces look like missing classes, but the real cause is version mismatch

I wasted hours debugging the wrong direction before finding this simple fix.

Common Mistakes to Avoid

Here are other common pitfalls:

  • Milestone versions (M1, M2) have different Boot mappings than release versions
  • Release notes mention compatibility - but few developers read them
  • Breaking changes are documented - like “Camden.SR5 adds Boot 1.5.x compatibility”

Quick Reference: Modern Spring Cloud Versions

If you’re working with recent Spring Boot versions, here’s a quick mapping:

Modern Spring Boot / Spring Cloud versions
Boot 3.4.x  -> 2024.0.x (Moondog)
Boot 3.3.x  -> 2023.0.x (Leyton) - includes 2023.0.0 to 2023.0.5
Boot 3.2.x  -> 2023.0.x (Leyton)
Boot 2.7.x  -> 2021.0.x ( Jubilee)
Boot 2.6.x  -> 2021.0.x ( Jubilee)
Boot 2.5.x  -> 2020.0.x (Ilford)
Boot 2.4.x  -> 2020.0.x (Ilford)

For the full and current matrix, always check: https://spring.io/projects/spring-cloud

Summary

NoClassDefFoundError with Spring Cloud usually indicates a version mismatch between Spring Boot and Spring Cloud dependencies. The fix is simple: match your Spring Cloud release train to the compatible Spring Boot version using the official compatibility matrix.

For my specific case:

  • Problem: Spring Boot 1.5.2.RELEASE with Camden.SR4 caused NamedContextFactory$Specification class not found
  • Solution: Use Camden.SR5+ (which added Boot 1.5.x support) or switch to Edgware/Dalston

Always verify compatibility before you start coding - it saves hours of debugging runtime class loading failures.

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!

Comments

Tags: