AssertionError: Must not defer during final iteration, when subclassing pydantic BaseModel and using a forward referenced type variable at the same class definition

[ofarukdogancay]

Crash Report

A forward reference of a generic type variable crashes mypy if the forward reference belongs to a Pydantic BaseModel. I tried replicating the issue with simpler classes by examining Pydantic’s quirks but couldn’t narrow it down further.

This works:

import typing
from pydantic import BaseModel

class Foo: ...

R = typing.TypeVar("R", bound="Foo")

class FooBar(BaseModel, typing.Generic[R]): ...

This does too:

import typing


R = typing.TypeVar("R", bound="Foo")

class Foo: ...
class Bar: ...

class FooBar(Bar, typing.Generic[R]): ...

But the following does not. Mypy outputs mypy_example/test.py:9: error: INTERNAL ERROR specifically on the line:

class FooBar(Bar, typing.Generic[R]): ...

import typing
from pydantic import BaseModel

R = typing.TypeVar("R", bound="Foo")

class Foo: ...

class FooBar(BaseModel, typing.Generic[R]): ...

Traceback

mypy 1.19.0+dev.feeb3f00a63d31cf5c7369885c4dd4a294133f59

Traceback (most recent call last):
  File "mypy/__main__.py", line 15, in console_entry
    main()
  File "mypy/main.py", line 127, in main
    res, messages, blockers = run_build(sources, options, fscache, t0, stdout, stderr)
  File "mypy/main.py", line 211, in run_build
    res = build.build(sources, options, None, flush_errors, fscache, stdout, stderr)
  File "mypy/build.py", line 196, in build
    result = _build(...)
  File "mypy/build.py", line 272, in _build
    graph = dispatch(sources, manager, stdout)
  File "mypy/build.py", line 2946, in dispatch
    process_graph(graph, manager)
  File "mypy/build.py", line 3346, in process_graph
    process_stale_scc(graph, scc, manager)
  File "mypy/build.py", line 3441, in process_stale_scc
    mypy.semanal_main.semantic_analysis_for_scc(graph, scc, manager.errors)
  File "mypy/semanal_main.py", line 96, in semantic_analysis_for_scc
    process_functions(graph, scc, patches)
  File "mypy/semanal_main.py", line 294, in process_functions
    process_top_level_function(...)
  File "mypy/semanal_main.py", line 333, in process_top_level_function
    deferred, incomplete, progress = semantic_analyze_target(...)
  File "mypy/semanal_main.py", line 399, in semantic_analyze_target
    analyzer.refresh_partial(...)
  File "mypy/semanal.py", line 661, in refresh_partial
    self.accept(node)
  File "mypy/semanal.py", line 7371, in accept
    node.accept(self)
  File "mypy/nodes.py", line 971, in accept
    return visitor.visit_func_def(self)
  File "mypy/semanal.py", line 927, in visit_func_def
    self.analyze_func_def(defn)
  File "mypy/semanal.py", line 972, in analyze_func_def
    self.defer(defn)
  File "mypy/semanal.py", line 7017, in defer
    assert not self.final_iteration, "Must not defer during final iteration"
AssertionError: Must not defer during final iteration

To Reproduce

import typing
from pydantic import BaseModel

R = typing.TypeVar("R", bound="Foo")

class Foo: ...

class FooBar(BaseModel, typing.Generic[R]): ...

Your Environment

UV Managed python virtual environment with only local build of mypy from master and pydantic

• Pydantic version used: 2.11.7
• Mypy version used: 1.19.0+dev.feeb3f00a63d31cf5c7369885c4dd4a294133f59
• Mypy command-line flags: --show-traceback
• Mypy configuration options from mypy.ini (and other config files): none
• Python version used: 3.13.5
• Operating system and version: macOS Sequoia 15.5

[ofarukdogancay]

typo: error occurs on line 'class FooBar(BaseModel, typing.Generic[R]): ...'

Reproduce example is still correct text reference was for a Bar(BaseModel) class. Both versions raise the same error.

[brianschubert]

Hmm, no luck reproducing this with the given setup:

$ uv run --python 3.13 -w pydantic==2.11.7 -w 'mypy @ git+https://github.com/python/mypy.git' mypy --show-traceback --cache-dir=/dev/null /dev/stdin <<EOF
import typing
from pydantic import BaseModel

R = typing.TypeVar("R", bound="Foo")

class Foo: ...

class FooBar(BaseModel, typing.Generic[R]): ...
EOF
Success: no issues found in 1 source file

[wyattscarpenter]

Related, possibly a duplicate (same error message, seems to be caused by pydantic plugin in similar circumstances): #15927

[ofarukdogancay]

Hmm, no luck reproducing this with the given setup:

$ uv run --python 3.13 -w pydantic==2.11.7 -w 'mypy @ git+https://github.com/python/mypy.git' mypy --show-traceback --cache-dir=/dev/null /dev/stdin <<EOF
import typing
from pydantic import BaseModel

R = typing.TypeVar("R", bound="Foo")

class Foo: ...

class FooBar(BaseModel, typing.Generic[R]): ...
EOF
Success: no issues found in 1 source file

Sorry, mypy pydantic plugin should have been included. Minimum pyproject.toml for example:

[project]
name = "mypy-test"
version = "0.1.0"
requires-python = ">=3.13"
dependencies = [
    "pydantic>=2.11.7",
]

[tool.mypy]
plugins = ['pydantic.mypy']

Build on 1.19.0+dev.feeb3f00a63d31cf5c7369885c4dd4a294133f59 reproduces crash on a clean environment.

[ofarukdogancay]

a more raw example with a requirements.txt and mypy.ini

requirements.txt

annotated-types==0.7.0
mypy @ file:///Users/**/mypy  # local clone
mypy_extensions==1.1.0
pathspec==0.12.1
pydantic==2.11.9
pydantic_core==2.33.2
typing-inspection==0.4.1
typing_extensions==4.15.0

mypy.ini

[mypy]
plugins = pydantic.mypy

code

import typing


import pydantic

R = typing.TypeVar("R", bound="Foo")

class Foo: ...

class Bar(pydantic.BaseModel, typing.Generic[R]): ...

python -V
Python 3.13.5

[ofarukdogancay]

Related code block at pydantic mypy plugin:

pydantic/mypy.py#L324

[sterliakov]

I'll try to PR this to pydantic tonight, the problem is there. Every iteration after deferral preserves previously added methods intact, renaming them to unique unused names.

https://github.com/pydantic/pydantic/blob/d13c8faccd86db2c48f744d490a71115f5f6c200/pydantic/mypy.py#L1333-L1338

Excluding plugin_generated methods there should definitely help, but there's one more bug. I' not sure that I have accounted for everything here, but the following diff resolves the plugin crash:

diff --git a/pydantic/mypy.py b/pydantic/mypy.py
index 1ac1b8761..e5d866a69 100644
--- a/pydantic/mypy.py
+++ b/pydantic/mypy.py
@@ -1286,7 +1286,7 @@ def add_method(
     # to avoid clashes and problems in the semantic analyzer.
     if name in info.names:
         sym = info.names[name]
-        if sym.plugin_generated and isinstance(sym.node, FuncDef):
+        if sym.plugin_generated and isinstance(sym.node, (FuncDef, Decorator)):
             cls.defs.body.remove(sym.node)  # pragma: no cover
 
     if isinstance(api, SemanticAnalyzerPluginInterface):
@@ -1333,9 +1333,12 @@ def add_method(
     # NOTE: we would like the plugin generated node to dominate, but we still
     # need to keep any existing definitions so they get semantically analyzed.
     if name in info.names:
-        # Get a nice unique name instead.
-        r_name = get_unique_redefinition_name(name, info.names)
-        info.names[r_name] = info.names[name]
+        sym = info.names[name]
+        if not sym.plugin_generated:
+            # plugin-generated nodes are most likely our own - overwrite them.
+            # Otherwise, get a nice unique name instead.
+            r_name = get_unique_redefinition_name(name, info.names)
+            info.names[r_name] = info.names[name]
 
     # Add decorator for is_classmethod
     # The dataclasses plugin claims this is unnecessary for classmethods, but not including it results in a
@@ -1354,7 +1357,7 @@ def add_method(
     sym.plugin_generated = True
     info.names[name] = sym
 
-    info.defn.defs.body.append(func)
+    info.defn.defs.body.append(sym.node)
 
 
 def parse_toml(config_file: str) -> dict[str, Any] | None:

[ofarukdogancay]

Thx. It works.