python/cpython · error · ValueError

Invalid format

Error message

Invalid format: {format!r}

What it means

The final else of the format dispatch in call_annotate_function raises ValueError('Invalid format: {format!r}') when the format argument matches none of the known Format members. This guards the public entry point against arbitrary integers or stale enum values passed as the format parameter.

Solutions

1. Pass an actual Format enum member: Format.VALUE, Format.STRING, or Format.FORWARDREF.
2. Validate dynamic values with `isinstance(fmt, Format)` (or Format.try_value) before calling.
3. Do not hardcode integer format values; reference the enum so code survives value changes.

Example fix

# before
ann = call_annotate_function(f.__annotate__, format='VALUE')  # ValueError: Invalid format: 'VALUE'

# after
from annotationlib import Format
ann = call_annotate_function(f.__annotate__, format=Format.VALUE)

from annotationlib import Format

def normalize_format(fmt):
    return Format(fmt)  # raises ValueError for invalid values, use as pre-check

from annotationlib import Format
import enum

def is_valid_format(fmt) -> bool:
    return isinstance(fmt, Format) or (isinstance(fmt, int) and fmt in Format._value2member_map_)

try:
    ann = call_annotate_function(annotate, format=fmt)
except ValueError as e:
    if 'Invalid format' in str(e):
        raise ValueError(f'unsupported annotation format {fmt!r}; use Format.VALUE/STRING/FORWARDREF') from e
    raise

When it happens

Trigger: call_annotate_function(annotate, format=3) or any integer not in Format._value2member_map_; passing a string like 'value' instead of Format.VALUE; passing a Format member from a different Python version after enum values changed.

Common situations: Serializing/deserializing format values across processes or Python versions; typos passing format names as strings; old codebases after enum member reordering.

Related errors

• Unsupported format
• .__annotations__ is neither a dict nor None
• The VALUE_WITH_FAKE_GLOBALS format is for internal use only
• annotate function does not support VALUE format
• Cannot stringify annotation containing string formatting

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

Appendix: source

Thrown at Lib/annotationlib.py:848

            if isinstance(result, ForwardRef):
                return result.evaluate(format=Format.FORWARDREF)
            else:
                return result
        else:
            return {
                key: (
                    val.evaluate(format=Format.FORWARDREF)
                    if isinstance(val, ForwardRef)
                    else val
                )
                for key, val in result.items()
            }
    elif format == Format.VALUE:
        # Should be impossible because __annotate__ functions must not raise
        # NotImplementedError for this format.
        raise RuntimeError("annotate function does not support VALUE format")
    else:
        raise ValueError(f"Invalid format: {format!r}")


def _build_closure(annotate, owner, is_class, stringifier_dict, *, allow_evaluation):
    if not annotate.__closure__:
        return None, None
    new_closure = []
    cell_dict = {}
    for name, cell in zip(annotate.__code__.co_freevars, annotate.__closure__, strict=True):
        cell_dict[name] = cell
        new_cell = None
        if allow_evaluation:
            try:
                cell.cell_contents
            except ValueError:
                pass
            else:
                new_cell = cell
        if new_cell is None:

View on GitHub (pinned to bc6749cc3b)