python/cpython · error · ValueError

Day of the year directive '%j' is not compatible with ISO ye

Error message

Day of the year directive '%j' is not compatible with ISO year directive '%G'. Use '%Y' instead.

What it means

In the ambiguity-resolution block of _strptime, if the ISO year directive %G produced a value and the day-of-year directive %j also produced one (both map to absolute day positions), the two can contradict, so a ValueError tells you to use the regular year %Y with %j instead.

Source

Thrown at Lib/_strptime.py:737

            # it can be something other than -1.
            found_zone = found_dict['Z'].lower()
            for value, tz_values in enumerate(locale_time.timezone):
                if found_zone in tz_values:
                    # Deal with bad locale setup where timezone names are the
                    # same and yet time.daylight is true; too ambiguous to
                    # be able to tell what timezone has daylight savings
                    if (time.tzname[0] == time.tzname[1] and
                       time.daylight and found_zone not in ("utc", "gmt")):
                        break
                    else:
                        tz = value
                        break

    # Deal with the cases where ambiguities arise
    # don't assume default values for ISO week/year
    if iso_year is not None:
        if julian is not None:
            raise ValueError("Day of the year directive '%j' is not "
                             "compatible with ISO year directive '%G'. "
                             "Use '%Y' instead.")
        elif iso_week is None or weekday is None:
            raise ValueError("ISO year directive '%G' must be used with "
                             "the ISO week directive '%V' and a weekday "
                             "directive ('%A', '%a', '%w', or '%u').")
    elif iso_week is not None:
        if year is None or weekday is None:
            raise ValueError("ISO week directive '%V' must be used with "
                             "the ISO year directive '%G' and a weekday "
                             "directive ('%A', '%a', '%w', or '%u').")
        else:
            raise ValueError("ISO week directive '%V' is incompatible with "
                             "the year directive '%Y'. Use the ISO year '%G' "
                             "instead.")

    leap_year_fix = False
    if year is None:

View on GitHub (pinned to bc6749cc3b)

Solutions

Use %Y with %j for ordinal dates: '%Y %j'
Keep %G only with %V and a weekday directive (%A/%a/%w/%u) for ISO week dates

Example fix

# before
>>> datetime.strptime('2020 100 3', '%G %j %u')
ValueError: Day of the year directive '%j' is not compatible with ISO year directive '%G'. Use '%Y' instead.

# after
>>> datetime.strptime('2020 100', '%Y %j')
datetime.datetime(2020, 4, 9, 0, 0)

Defensive patterns

Strategy: validation

Validate before calling

def check_iso_fmt(fmt: str) -> None:
    if '%G' in fmt.replace('%%', '') and '%j' in fmt.replace('%%', ''):
        raise ValueError('format mixes %G and %j; use %Y with %j')

Prevention

Pair %j only with %Y/%y (ordinal dates)
Pair %G only with %V + weekday (ISO week dates)
Decide once per data source which calendar the strings use and pin the format

When it happens

Trigger: datetime.strptime('2020 100 3', '%G %j %u') — any format combining %G and %j; %j is compatible only with %Y/%y, not with the ISO-week calendar year.

Common situations: ISO 8601 week-date strings mistakenly parsed with %j; mixing Ordinal-date formats (YYYY-DDD) with ISO week-date formats (YYYY-Www-D).

Related errors

AI-assisted analysis of python/cpython@bc6749cc3b (2026-08-14). Data as JSON: /api/errors/b894afdef827343e. Report an issue: GitHub.