python/cpython · error · ValueError

ISO year directive '%G' must be used with the ISO week direc

Error message

ISO year directive '%G' must be used with the ISO week directive '%V' and a weekday directive ('%A', '%a', '%w', or '%u').

What it means

The ISO year %G only makes sense together with the ISO week number %V and a weekday (%A, %a, %w, %u) — all three are needed to pin down a date. If %G matched but iso_week or weekday is None after processing, _strptime raises this ValueError.

Source

Thrown at Lib/_strptime.py:741

                    # 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:
        if month == 2 and day == 29:
            year = 1904  # 1904 is first leap year of 20th century
            leap_year_fix = True
        else:

View on GitHub (pinned to bc6749cc3b)

Solutions

  1. Add the weekday to input and format: '2020 W12 3' with '%G W%V %u'
  2. If the day is unknown, decide on a default (e.g. Monday) and append it before parsing

Example fix

# before
>>> datetime.strptime('2020 W12', '%G W%V')
ValueError: ISO year directive '%G' must be used with the ISO week directive '%V' and a weekday directive ('%A', '%a', '%w', or '%u').

# after
>>> datetime.strptime('2020 W12 1', '%G W%V %u')
datetime.datetime(2020, 3, 16, 0, 0)
Defensive patterns

Strategy: validation

Validate before calling

def complete_iso_week_input(s: str, fmt: str):
    if '%G' in fmt and '%V' not in fmt:
        fmt += ' %V'
        s += ' 01'
    if not any(d in fmt for d in ('%A', '%a', '%w', '%u')):
        fmt += ' %u'
        s += ' 1'
    return s, fmt

Prevention

When it happens

Trigger: datetime.strptime('2020', '%G') or datetime.strptime('2020 W12', '%G %V') — %G present without a weekday, or without %V at all.

Common situations: Parsing partial ISO week-date strings such as '2020-W12' and forgetting the day component; truncated ISO strings copied from reports.

Related errors

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