{"record":{"id":"84aca518e8fb9116","repo":"python/cpython","slug":"annotate-function-does-not-support-value-format","errorCode":null,"errorMessage":"annotate function does not support VALUE format","messagePattern":"annotate function does not support VALUE format","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"Lib/annotationlib.py","lineNumber":846,"sourceCode":"        globals.transmogrify(cell_dict)\n        if _is_evaluate:\n            if isinstance(result, ForwardRef):\n                return result.evaluate(format=Format.FORWARDREF)\n            else:\n                return result\n        else:\n            return {\n                key: (\n                    val.evaluate(format=Format.FORWARDREF)\n                    if isinstance(val, ForwardRef)\n                    else val\n                )\n                for key, val in result.items()\n            }\n    elif format == Format.VALUE:\n        # Should be impossible because __annotate__ functions must not raise\n        # NotImplementedError for this format.\n        raise RuntimeError(\"annotate function does not support VALUE format\")\n    else:\n        raise ValueError(f\"Invalid format: {format!r}\")\n\n\ndef _build_closure(annotate, owner, is_class, stringifier_dict, *, allow_evaluation):\n    if not annotate.__closure__:\n        return None, None\n    new_closure = []\n    cell_dict = {}\n    for name, cell in zip(annotate.__code__.co_freevars, annotate.__closure__, strict=True):\n        cell_dict[name] = cell\n        new_cell = None\n        if allow_evaluation:\n            try:\n                cell.cell_contents\n            except ValueError:\n                pass\n            else:","sourceCodeStart":828,"sourceCodeEnd":864,"githubUrl":"https://github.com/python/cpython/blob/bc6749cc3b5ae4a5e88a6cc2d5b3bebbe354eae6/Lib/annotationlib.py#L828-L864","documentation":"Inside call_annotate_function's VALUE branch, an annotate function that raised NotImplementedError for Format.VALUE violates the PEP 649 contract (annotate functions must support VALUE). The code marks this 'should be impossible' and raises RuntimeError, signaling a broken or hand-crafted __annotate__ rather than caller error.","triggerScenarios":"Attaching a custom __annotate__ that raises NotImplementedError unconditionally or for Format.VALUE; objects built by metaclasses or decorators that synthesize __annotate__ incorrectly; mocks/stubs that raise NotImplementedError for all calls.","commonSituations":"Test doubles or protocol implementations where every method raises NotImplementedError; decorator libraries fabricating __annotate__ to opt out of annotations; bugs in code generators that emit __annotate__ functions.","solutions":["Fix the custom __annotate__ so it returns a dict for Format.VALUE (it may special-case STRING/FORWARDREF but must handle VALUE).","If you cannot support annotation at all, set __annotate__ to None / delete it instead of raising.","Catch RuntimeError defensively when introspecting third-party objects you do not control."],"exampleFix":"# before\ndef __annotate__(format):\n    raise NotImplementedError  # breaks contract -> RuntimeError from call_annotate_function\n\n# after\ndef __annotate__(format):\n    return {'x': int}","handlingStrategy":"try-catch","validationCode":"def annotate_supports_value(annotate) -> bool:\n    try:\n        return isinstance(annotate(1), dict)  # 1 == Format.VALUE value if stable; prefer Format.VALUE\n    except NotImplementedError:\n        return False\n    except Exception:\n        return False","typeGuard":"def has_sane_annotate(obj) -> bool:\n    ann = getattr(obj, '__annotate__', None)\n    if ann is None:\n        return True  # no custom implementation, nothing to violate\n    try:\n        from annotationlib import Format\n        return isinstance(ann(Format.VALUE), dict)\n    except (NotImplementedError, TypeError, ValueError):\n        return False","tryCatchPattern":"try:\n    ann = annotationlib.get_annotations(obj, format=Format.VALUE)\nexcept RuntimeError as e:\n    if 'does not support VALUE' in str(e):\n        ann = {}  # object has a broken __annotate__; degrade gracefully\n    else:\n        raise","preventionTips":["Custom __annotate__ must return a dict for every format, especially VALUE","Do not make __annotate__ raise NotImplementedError unconditionally","Test custom __annotate__ against all public formats"],"tags":["python","annotations","pep649","contract-violation","runtimeerror"],"backgroundTag":null,"analyzedSha":"bc6749cc3b5ae4a5e88a6cc2d5b3bebbe354eae6","analyzedAt":"2026-08-14T22:01:13.976Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}