Fix Jackson LocalDate Serialization and Time Module Errors
Fix the Jackson error about Java 8 date/time types by registering the time module, choosing ISO strings over timestamps and setting the format in one place.

A LocalDate field makes serialization fail:
com.fasterxml.jackson.databind.exc.InvalidDefinitionException: Java 8 date/time type `java.time.LocalDate` not supported by default: add Module "com.fasterxml.jackson.datatype:jackson-datatype-jsr310" to enable handlingJackson 2 was created before java.time and keeps date and time support in an optional module. The message names the module, which is useful. Jackson 3, which Spring Boot 4 uses by default (packages under tools.jackson), includes java.time support in the databind core, so the error disappears there. If you see it, you are on Jackson 2 with a mapper that has not registered the module. The date types themselves are described in the modern Java guide.
Fix in a Spring Boot application
You usually do not have to do anything, as long as you use the Boot-provided ObjectMapper: Spring Boot registers JavaTimeModule when jackson-datatype-jsr310 is on the classpath, and spring-boot-starter-json brings it. The failure comes from a mapper that bypasses Boot's:
ObjectMapper mapper = new ObjectMapper(); // no modules registeredInject Boot's instead:
@Service
class ExportService {
private final ObjectMapper mapper;
ExportService(ObjectMapper mapper) {
this.mapper = mapper;
}
}In a test, @JsonTest provides the configured mapper. A RestClient or WebClient built by hand should use Boot's builder (RestClient.Builder) so it picks up the same mapper.
Fix in plain Java
Add the dependency and register the module:
<dependency>
<groupId>com.fasterxml.jackson.datatype</groupId>
<artifactId>jackson-datatype-jsr310</artifactId>
</dependency>ObjectMapper mapper = JsonMapper.builder()
.addModule(new JavaTimeModule())
.disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS)
.build();With the module but without disabling WRITE_DATES_AS_TIMESTAMPS, a LocalDate serializes as an array, [2026,3,14], and an Instant as a decimal number of seconds. Both are valid and neither is what most clients expect.
Choose the format
| Java type | ISO-8601 output |
|---|---|
LocalDate | "2026-03-14" |
LocalDateTime | "2026-03-14T10:15:30" |
Instant | "2026-03-14T10:15:30Z" |
OffsetDateTime | "2026-03-14T10:15:30+02:00" |
Duration | "PT1H30M" |
For an API, use Instant or OffsetDateTime for moments in time, since they identify a point unambiguously. A LocalDateTime has no time zone, and two clients will interpret it differently. Use LocalDate only for calendar dates such as a birthday.
In Spring Boot configuration:
spring.jackson.serialization.write-dates-as-timestamps=false
spring.jackson.time-zone=UTCPer-field format
public record Booking(
@JsonFormat(pattern = "dd/MM/yyyy") LocalDate checkIn) {}Use this for a legacy client that insists on another format. Keep it exceptional, because a mixed-format API is confusing.
Deserialization
Reading works the same way: with the module, "2026-03-14" becomes a LocalDate. A string in another format throws DateTimeParseException wrapped in a Jackson exception, and in Spring MVC it becomes a 400 from [HttpMessageNotReadableException](/library/httpmessagenotreadableexception-fix-json-parse-error).
What each setting actually writes
The fix is one line, but the output depends on two more settings, and choosing them is where API compatibility is won or lost. This program serialises the same record three ways, using Jackson 2.20.0 and jackson-datatype-jsr310 2.20.0 on a plain classpath.
record Invoice(String number, LocalDate issued, Instant paidAt) {}
Invoice inv = new Invoice("INV-1", LocalDate.of(2025, 3, 14), Instant.parse("2025-03-14T09:00:00Z"));
try {
new ObjectMapper().writeValueAsString(inv);
} catch (Exception e) {
System.out.println(e.getClass().getName());
System.out.println(e.getMessage().lines().findFirst().get());
}
ObjectMapper timestamps = new ObjectMapper().registerModule(new JavaTimeModule());
System.out.println("default " + timestamps.writeValueAsString(inv));
ObjectMapper iso = new ObjectMapper().registerModule(new JavaTimeModule())
.disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS);
System.out.println("iso " + iso.writeValueAsString(inv));com.fasterxml.jackson.databind.exc.InvalidDefinitionException
Java 8 date/time type `java.time.LocalDate` not supported by default: add Module "com.fasterxml.jackson.datatype:jackson-datatype-jsr310" to enable handling (or disable `MapperFeature.REQUIRE_HANDLERS_FOR_JAVA8_TIMES`) (through reference chain: Jk$Invoice["issued"])
default {"number":"INV-1","issued":[2025,3,14],"paidAt":1741942800.000000000}
iso {"number":"INV-1","issued":"2025-03-14","paidAt":"2025-03-14T09:00:00Z"}The first line is the error you searched for, and the module named in it is the cure. After registering JavaTimeModule, the output is valid JSON but probably not what an API client expects: LocalDate becomes an array [2025,3,14] and Instant becomes seconds with nine decimals. The module defaults to timestamps because WRITE_DATES_AS_TIMESTAMPS is on in a bare ObjectMapper. Turning it off gives ISO 8601 strings, which every language can parse and humans can read in a log.
Spring Boot turns that feature off for you, so a Boot application that registers the module through the auto-configured mapper writes ISO strings without further settings. The array output surfaces in code that builds its own new ObjectMapper(), in a test utility, a Kafka serialiser or a Redis cache, and the mismatch with the REST API is the bug that follows.
Share one mapper, not three
Having several mappers configured differently is the root cause of most date format bugs. Inject the Boot mapper wherever JSON is produced, or build one shared factory method for code outside Spring.
public final class Json {
public static final ObjectMapper MAPPER = JsonMapper.builder()
.addModule(new JavaTimeModule())
.disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS)
.disable(DeserializationFeature.ADJUST_DATES_TO_CONTEXT_TIME_ZONE)
.build();
private Json() {}
}ADJUST_DATES_TO_CONTEXT_TIME_ZONE is on by default and shifts parsed zoned values into the mapper's zone, which silently changes an offset such as +07:00 into UTC. Disabling it keeps the offset the client sent. Whether you want that depends on the contract; the point is to decide once.
Reading dates the client got wrong
The deserialising side fails loudly and the message is easy to read when you know where to look.
InvalidFormatException: Cannot deserialize value of type `java.time.LocalDate` from String "14/03/2025": Failed to deserialize java.time.LocalDate: (java.time.format.DateTimeParseException) Text '14/03/2025' could not be parsed at index 0The standard formatter expects 2025-03-14. Do not teach the server to accept every format a client might send; reject the request with a 400 that names the field and the expected format, and fix the client. If you must accept one legacy format, annotate that field only: @JsonFormat(pattern = "dd/MM/yyyy"). A global custom format hides the next client's mistake, and two formats in one API make the contract ambiguous.
Durations and other types the module covers
The module handles more than dates. Duration writes as seconds with nine decimals under the timestamp setting, so Duration.ofMinutes(90) becomes 5400.000000000, and as PT1H30M under ISO. Period, Year, YearMonth, ZoneId and MonthDay are covered too. For a field that is a duration in the domain, document the unit in the API description, because 5400.000000000 does not say seconds to a reader.
When a library you do not control produces the JSON, as some cloud SDKs do, check which mapper it uses before assuming your configuration applies. A bean named ObjectMapper in your context does not change the mapper inside a third-party client.
Jackson 3
Jackson 3 moves to a new package, tools.jackson, and includes java.time support in the core databind module, so the explicit module registration goes away there. The message above is a Jackson 2 problem. Spring Boot 4 supports Jackson 3, and applications that stay on Jackson 2 keep the behaviour described here. Check which major version your dependency tree resolves with mvn dependency:tree before applying a fix from the wrong generation.
Where this does not apply
Query and path parameters are not Jackson: use @DateTimeFormat(iso = DateTimeFormat.ISO.DATE) for LocalDate request parameters. The java.sql.Date and java.util.Date types are supported by Jackson without a module, which is why old code does not hit this error. The error usually shows up together with unrecognized fields when a mapper is built by hand, and the API rules for dates are in REST API design rules. The [Jackson java.time module documentation](https://github.com/FasterXML/jackson-modules-java8) and the Spring Boot JSON reference are the primary sources.


