What Breaking Changes Does Jackson 3 Introduce When Upgrading Spring Boot 4?

Spring Boot 4 upgrades the Jackson library to version 3, and the change is far more than a simple version bump. The article explains four major breaking changes, their impact on existing code, and practical migration tips.

1. Package Reorganization

The core Jackson packages have been moved from com.fasterxml to tools.jackson. Only the core API classes change their package; annotation classes remain in the old package.

import com.fasterxml.jackson.core.JsonProcessingException; // Jackson 2 (old)
import com.fasterxml.jackson.core.type.TypeReference;
import com.fasterxml.jackson.databind.ObjectMapper;

import tools.jackson.core.JacksonException; // Jackson 3 (new)
import tools.jackson.core.type.TypeReference;
import tools.jackson.databind.ObjectMapper;

Do not globally replace com.fasterxml in your project, otherwise annotation imports will break.

2. ObjectMapper Replaced by JsonMapper

Jackson 2’s mutable ObjectMapper is deprecated in favor of an immutable JsonMapper built via a builder. The configuration is locked after build(), making the mapper thread‑safe.

JsonMapper mapper = JsonMapper.builder()
    .enable(SerializationFeature.INDENT_OUTPUT)
    .disable(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES)
    .build();

Creating a new ObjectMapper() now yields a default configuration; custom settings must be applied through the builder.

3. Date Serialization Change

Jackson 3 switches the default date output from a numeric timestamp (Long) to an ISO‑8601 string, which is a common source of front‑end integration failures.

Jackson 2 default: timestamp (e.g., {"now":1767588151648})

Jackson 3 default: ISO‑8601 string (e.g., {"now":"2026-01-05T02:02:31Z"})

If your front‑end code or tests hard‑code timestamp parsing, the upgrade will cause crashes.

4. Exception Handling – Checked to Runtime

All Jackson‑related checked exceptions (e.g., IOException from readValue) are now wrapped in RuntimeException, simplifying stream and lambda usage.

// Jackson 3: no need to catch IOException
list.stream()
    .map(o -> jsonMapper.writeValueAsString(o))
    .toList();

This design aligns Jackson with modern Java practices, improving code cleanliness.

Migration Tips

For a quick fix that mimics Jackson 2 behavior, add the following to application.yml (not recommended for long‑term use):

spring:
  jackson:
    use-jackson2-defaults: true  # forces Jackson 3 to behave like Jackson 2

However, the preferred approach is to update imports, switch to JsonMapper, and adjust date handling.