Serguey Asael Shinder: DateTimeFormatter's YYYY is the week-based year, and it is wrong a few days a year

26 September 2026, 12:55 · by Serguey Asael Shinder / Serguey Shinder

Here is a pattern that passes code review, passes tests, and ships:

DateTimeFormatter f = DateTimeFormatter.ofPattern("YYYY-MM-dd");

The table in the javadoc for java.time.format.DateTimeFormatter lists three different "year" letters. u is year, y is year-of-era, and Y is week-based-year. The builder's javadoc, DateTimeFormatterBuilder.appendPattern, is more specific about what Y does: it appends a special localized WeekFields element for the week-based year. So the value depends on how the formatter's locale defines a week.

A week-based year is not the calendar year. As the WeekFields javadoc puts it, the first week may start in the previous calendar year, and the first few days of a calendar year may belong to the week-based year of the previous one. For fifty-one weeks of the year the two agree, so every test written in September passes.

Serguey Asael Shinder: DateTimeFormatter's YYYY is the week-based year, and it is wrong a few days a year — DateTimeFormatter's YYYY is the week-based year, and it is wrong a few days a year — Serguey Asael Shinder

The coming new year shows both directions. I have not run this here - there is no JDK on the machine I am writing on - so the dates below are worked out from the definitions, not from output.

Under the ISO rules (weeks start on Monday, the first week needs at least four days), 1 January 2027 is a Friday and falls in ISO week 53 of 2026. A date formatted with YYYY-MM-dd would print as 2026-01-01, a year behind.
Under a week definition that starts on Sunday and needs only one day in the first week, which is the usual configuration for the United States, the week containing 1 January 2027 begins on Sunday 27 December 2026. Those last days of December would print as 2027-12-27 to 2027-12-31, a year ahead.

Because the week rules come from the locale, the same line of code can be wrong on different days on different servers, which makes the bug look intermittent when it is entirely deterministic.

The fix is one character: use uuuu (or yyyy) for a calendar date. Keep Y only when you really mean ISO-style week numbering, and then pair it with w for the week and make the rules explicit with WeekFields.ISO rather than inheriting them from whatever locale the JVM starts with. A cheap guard is a test that formats 31 December and 1 January of a year where the two years diverge - 2026 into 2027 is one - under the locales you actually deploy.