Introduction

Upgrading Spring Boot from 2.3.9 to 2.6.3 often exposes behavior that was tolerated before but is no longer allowed. The most common failures come from circular bean references, path matching changes, and older dependency assumptions. The fastest way to recover is to identify the exact breaking change instead of treating the upgrade as one generic error.

Start With the Most Common Breaking Change

Spring Boot 2.6 disables circular references by default. Applications that worked before can now fail at startup with bean creation errors.

If you see a circular dependency message, the correct long-term fix is to break the cycle in your design. As a temporary compatibility bridge, you can re-enable the old behavior.

spring.main.allow-circular-references=true

That property is useful for fast diagnosis, but it should not be the permanent answer unless you have reviewed the dependency graph carefully.

Path Matching Changed in Spring MVC

Another upgrade surprise is URL matching behavior. Spring Boot 2.6 switches to PathPatternParser by default, which can affect applications that depend on old AntPathMatcher behavior.

If request mappings or Swagger integrations start failing, test this compatibility setting:

spring.mvc.pathmatch.matching-strategy=ant_path_matcher

This is especially common in applications using older Springfox versions or custom path-matching assumptions.

Check Dependency Compatibility, Not Only Boot Version

A Boot upgrade also upgrades managed dependency versions. Errors may come from:

• Spring Security configuration changes.
• Springfox incompatibility.
• Old starters pinned to versions that no longer match.
• Jakarta or validation transitive changes.

Use dependency insight commands to inspect what changed.

mvn dependency:tree

Or with Gradle:

./gradlew dependencies

The goal is to find libraries that were compatible with 2.3.9 but not with 2.6.3.

Upgrade One Layer at a Time

If the app fails during startup, split diagnosis into layers:

1. Boot application startup.
2. MVC routing.
3. Security config.
4. Data access and migrations.
5. Tests and contract-level behavior.

This is faster than changing many properties at once and hoping the error disappears.

Example: Circular Dependency Refactor

Suppose two services inject each other directly. That often worked before, but now fails.

1@Service
2public class BillingService {
3    private final NotificationService notificationService;
4
5    public BillingService(NotificationService notificationService) {
6        this.notificationService = notificationService;
7    }
8}
9
10@Service
11public class NotificationService {
12    private final BillingService billingService;
13
14    public NotificationService(BillingService billingService) {
15        this.billingService = billingService;
16    }
17}

One fix is extracting shared behavior into a third service so the cycle disappears.

1@Service
2public class BillingNotifier {
3    public void notifyBillingEvent(String message) {
4        System.out.println(message);
5    }
6}

Then each original service depends on BillingNotifier instead of on each other.

Example: Failing MVC Behavior After Upgrade

If controller mappings behave strangely, write one focused MVC test around the failing path.

1@SpringBootTest
2@AutoConfigureMockMvc
3class RoutingTest {
4
5    @Autowired
6    MockMvc mockMvc;
7
8    @Test
9    void userEndpointStillResolves() throws Exception {
10        mockMvc.perform(get("/api/users/42"))
11               .andExpect(status().isOk());
12    }
13}

This keeps upgrade debugging concrete. Instead of guessing, you verify one broken contract at a time.

Review Release Notes With Intent

For Spring Boot upgrades, release notes are worth reading because changes are often intentional. In this specific upgrade range, pay attention to:

• Circular reference defaults.
• Path matching defaults.
• Actuator endpoint exposure changes.
• Security configuration assumptions.

That reading is not busywork. It is usually faster than chasing side effects blindly through stack traces.

Practical Upgrade Workflow

A disciplined workflow looks like this:

• Upgrade Boot version only.
• Run tests and capture first failing category.
• Apply the minimal compatibility setting if needed.
• Refactor root cause where possible.
• Remove temporary compatibility switches once stable.

This produces a cleaner final codebase than accumulating permanent workaround properties.

Common Pitfalls

• Treating every upgrade failure as one generic Boot problem.
• Re-enabling old behavior globally without understanding the root cause.
• Ignoring dependency compatibility and checking only application code.
• Changing several framework settings at once, which hides the real cause.
• Skipping focused regression tests around failing routes or beans.

Summary

• Spring Boot 2.6.3 commonly breaks apps through circular-reference and path-matching changes.
• Start by identifying the exact failure category from logs.
• Use compatibility properties only as short-term diagnosis tools.
• Check managed dependency compatibility, not just Boot version number.
• Add focused tests around the behavior that changed so the upgrade becomes reproducible and safe.