Union changes in Python 3.14 crash mypy

[srittau]

Crash Report

typeshed PR python/typeshed#13740, which adapts the changes to Union in Python 3.14 for typeshed crash mypy. (When running the tests with Python 3.14 or 3.15. Older Python versions are fine.)

The changes

Traceback

python tests/stubtest_stdlib.py
 shell: /usr/bin/bash -e {0}
 env:
 PIP_DISABLE_PIP_VERSION_CHECK: 1
 FORCE_COLOR: 1
 TERM: xterm-256color
 pythonLocation: /opt/hostedtoolcache/Python/3.15.0-beta.2/x64
 PKG_CONFIG_PATH: /opt/hostedtoolcache/Python/3.15.0-beta.2/x64/lib/pkgconfig
 Python_ROOT_DIR: /opt/hostedtoolcache/Python/3.15.0-beta.2/x64
 Python2_ROOT_DIR: /opt/hostedtoolcache/Python/3.15.0-beta.2/x64
 Python3_ROOT_DIR: /opt/hostedtoolcache/Python/3.15.0-beta.2/x64
 LD_LIBRARY_PATH: /opt/hostedtoolcache/Python/3.15.0-beta.2/x64/lib
/opt/hostedtoolcache/Python/3.15.0-beta.2/x64/bin/python -m mypy.stubtest --check-typeshed --show-traceback --strict-type-check-only --custom-typeshed-dir . --allowlist stdlib/@tests/stubtest_allowlists/common.txt --allowlist stdlib/@tests/stubtest_allowlists/linux.txt --allowlist stdlib/@tests/stubtest_allowlists/py315.txt --allowlist stdlib/@tests/stubtest_allowlists/linux-py315.txt
/home/runner/work/typeshed/typeshed/stdlib/typing.pyi:1002: error: INTERNAL ERROR -- Please try using mypy master on GitHub:
https://mypy.readthedocs.io/en/stable/common_issues.html#using-a-development-mypy-build
Please report a bug at https://github.com/python/mypy/issues
version: 2.1.0
/home/runner/work/typeshed/typeshed/stdlib/typing.pyi:1002: note: use --pdb to drop into pdb
stdlib/typing_extensions.pyi:287: error: Overloaded function signatures 1 and 3 overlap with incompatible return types [overload-overlap]
Traceback (most recent call last):
 File "<frozen runpy>", line 201, in _run_module_as_main
 File "<frozen runpy>", line 87, in _run_code
 File "/opt/hostedtoolcache/Python/3.15.0-beta.2/x64/lib/python3.15/site-packages/mypy/stubtest.py", line 2593, in <module>
 sys.exit(main())
 File "/opt/hostedtoolcache/Python/3.15.0-beta.2/x64/lib/python3.15/site-packages/mypy/stubtest.py", line 2589, in main
 return test_stubs(parse_options(sys.argv[1:]))
 File "/opt/hostedtoolcache/Python/3.15.0-beta.2/x64/lib/python3.15/site-packages/mypy/stubtest.py", line 2419, in test_stubs
 modules = build_stubs(modules, options, find_submodules=not args.check_typeshed)
 File "/opt/hostedtoolcache/Python/3.15.0-beta.2/x64/lib/python3.15/site-packages/mypy/stubtest.py", line 2215, in build_stubs
 res = mypy.build.build(sources=sources, options=options)
 File "/opt/hostedtoolcache/Python/3.15.0-beta.2/x64/lib/python3.15/site-packages/mypy/build.py", line 422, in build
 result = build_inner(
 File "/opt/hostedtoolcache/Python/3.15.0-beta.2/x64/lib/python3.15/site-packages/mypy/build.py", line 537, in build_inner
 graph = dispatch(sources, manager, stdout, connect_threads)
 File "/opt/hostedtoolcache/Python/3.15.0-beta.2/x64/lib/python3.15/site-packages/mypy/build.py", line 4150, in dispatch
 process_graph(graph, manager)
 File "/opt/hostedtoolcache/Python/3.15.0-beta.2/x64/lib/python3.15/site-packages/mypy/build.py", line 4618, in process_graph
 done, still_working, results = manager.wait_for_done(graph)
 File "/opt/hostedtoolcache/Python/3.15.0-beta.2/x64/lib/python3.15/site-packages/mypy/build.py", line 1492, in wait_for_done
 process_stale_scc(graph, next_scc, self)
 File "/opt/hostedtoolcache/Python/3.15.0-beta.2/x64/lib/python3.15/site-packages/mypy/build.py", line 4792, in process_stale_scc
 graph[id].type_check_first_pass()
 File "/opt/hostedtoolcache/Python/3.15.0-beta.2/x64/lib/python3.15/site-packages/mypy/build.py", line 3414, in type_check_first_pass
 self.type_checker().check_first_pass(recurse_into_functions=recurse_into_functions)
 File "/opt/hostedtoolcache/Python/3.15.0-beta.2/x64/lib/python3.15/site-packages/mypy/checker.py", line 618, in check_first_pass
 self.accept(d)
 File "/opt/hostedtoolcache/Python/3.15.0-beta.2/x64/lib/python3.15/site-packages/mypy/checker.py", line 765, in accept
 stmt.accept(self)
 File "/opt/hostedtoolcache/Python/3.15.0-beta.2/x64/lib/python3.15/site-packages/mypy/nodes.py", line 1907, in accept
 return visitor.visit_assignment_stmt(self)
 File "/opt/hostedtoolcache/Python/3.15.0-beta.2/x64/lib/python3.15/site-packages/mypy/checker.py", line 3329, in visit_assignment_stmt
 self.check_type_alias_rvalue(s)
 File "/opt/hostedtoolcache/Python/3.15.0-beta.2/x64/lib/python3.15/site-packages/mypy/checker.py", line 3370, in check_type_alias_rvalue
 alias_type = self.expr_checker.accept(s.rvalue)
 File "/opt/hostedtoolcache/Python/3.15.0-beta.2/x64/lib/python3.15/site-packages/mypy/checkexpr.py", line 6176, in accept
 typ = self.accept_maybe_cache(node, type_context=type_context)
 File "/opt/hostedtoolcache/Python/3.15.0-beta.2/x64/lib/python3.15/site-packages/mypy/checkexpr.py", line 6211, in accept_maybe_cache
 typ = node.accept(self)
 File "/opt/hostedtoolcache/Python/3.15.0-beta.2/x64/lib/python3.15/site-packages/mypy/nodes.py", line 2697, in accept
 return visitor.visit_op_expr(self)
 File "/opt/hostedtoolcache/Python/3.15.0-beta.2/x64/lib/python3.15/site-packages/mypy/checkexpr.py", line 3559, in visit_op_expr
 return self.accept(e.analyzed)
 File "/opt/hostedtoolcache/Python/3.15.0-beta.2/x64/lib/python3.15/site-packages/mypy/checkexpr.py", line 6178, in accept
 typ = node.accept(self) # r-value type, when interpreted as a value expression
 File "/opt/hostedtoolcache/Python/3.15.0-beta.2/x64/lib/python3.15/site-packages/mypy/nodes.py", line 3420, in accept
 return visitor.visit_type_alias_expr(self)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^
 File "/opt/hostedtoolcache/Python/3.15.0-beta.2/x64/lib/python3.15/site-packages/mypy/checkexpr.py", line 4967, in visit_type_alias_expr
 return self.alias_type_in_runtime_context(alias.node, ctx=alias, alias_definition=True)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 File "/opt/hostedtoolcache/Python/3.15.0-beta.2/x64/lib/python3.15/site-packages/mypy/checkexpr.py", line 5024, in alias_type_in_runtime_context
 return self.chk.named_generic_type("types.UnionType", item.items)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 File "/opt/hostedtoolcache/Python/3.15.0-beta.2/x64/lib/python3.15/site-packages/mypy/checker.py", line 7788, in named_generic_type
 info = self.lookup_typeinfo(name)
 File "/opt/hostedtoolcache/Python/3.15.0-beta.2/x64/lib/python3.15/site-packages/mypy/checker.py", line 7797, in lookup_typeinfo
 assert isinstance(node, TypeInfo), node
 ~~~~~~~~~~^^^^^^^^^^^^^^^^
AssertionError: TypeAlias:723(
 UnionType
 Never
 False)

Your Environment

Command run was: /opt/hostedtoolcache/Python/3.15.0-beta.2/x64/bin/python -m mypy.stubtest --check-typeshed --show-traceback --strict-type-check-only --custom-typeshed-dir . --allowlist stdlib/@tests/stubtest_allowlists/common.txt --allowlist stdlib/@tests/stubtest_allowlists/linux.txt --allowlist stdlib/@tests/stubtest_allowlists/py315.txt --allowlist stdlib/@tests/stubtest_allowlists/linux-py315.txt

• Mypy version used: 2.1.0
• Python version used: 3.14.5/3.15.0b2
• Operating system and version: Crashed on Ubuntu, Windows, MacOS

[LordGiacomoS]

I've actually managed to seemingly "fix" this crash (used typeshed's stubtests in linux on python versions 3.14.5 and 3.15.0b1) (ee52790), but I don't consider the fork to be viable as a PR in its current state.

• There is an issue where without the updated typeshed version, mypy fails in a way that doesn't even explicitly tell the user to update their external typeshed.
• My fork still needs mypy's internal version of typeshed to be updated, but I'm hesitant to touch that part because it looks like it's meant to be kept in sync with typeshed's main branch.
• There are probably also other issues I haven't encountered with just the stubtests regarding how it actually behaves within functions.

---

Note from 2026-06-08:
I currently think that to solve the complex implementation issues, the best way to handle the code in mypy is to create another incomplete/experimental feature flag, which seems to be purpose made for this sort of problem, with the docs stating that "Some features may require several mypy releases to implement, for example due to their complexity, potential for backwards incompatibility, or ambiguous semantics that would benefit from feedback from the community."

Will work on updating my existing forked branch to use this flag (along with subsequent checks that a compatible version of Python and typeshed are being used).

---

Note from 2026-06-12:
Drafted a rough set of guardrails using the aforementioned incomplete/experimental feature flag here. Still not putting up a PR for this yet though, as I've run into another bug with the code that should be fixed first.

I know the code for checking is ugly, but it's about as good as I could make it while having to find a spot where setting up the guardrails would be possible, seemingly remotely appropriate, and limited in performance impact. Putting the checks into the general parsing loop would mean that at least the first check runs every time the containing function does, and a string comparison like what would be necessary seemed like it could get expensive if repeated excessively.

Sidenote: I genuinely think that the part of the change in Python that merged typing.Union and types.UnionType (and is now causing this bug) was a mistake and should be reverted in 3.16. Either that or make it consistent and also merge similar cases like builtins.None and types.NoneType -- a consistent change that directly contradicts the established way concepts are represented in the code would still be better than a change to one specific case that is inconsistent with everything else.

The newly discovered bug in the code for anyone who is curious

from typing import Union

def tester1(val: Union) -> bool:
 return issubclass(bool, val)
assert tester1(str | int)

In mypy, raises an error that "Argument 1 to "tester1" has incompatible type "Union | type[str]"; expected "Union" [arg-type]"
At runtime, no issues arise.

---

Note from 2026-06-17:
Have finished creating a branch that passes the existing set of tests under mypy's "Tests" suite (see here). Now I just need to learn mypy's test syntax and set up tests for the changes, then it should be good to go for an initial PR to allow for people more familiar with mypy's codebase to provide feedback.

---

Note from 2026-06-24:
While working on writing tests, I've been encountering a handful of bugs that need fixing with my code.

I've also encountered an issue with how mypy evaluates or-syntax unions that is technically independent of my changes, but is a much more minor issue without them, and makes the tests I'm writing fail, so I'm currently working to fix that.

A more detailed explanation of the adjacent mypy issue I found

When running reveal_type(typing.Union[str, int]), I currently[1] get a long revealed type with overloads that translates to typing.Union[str, int][2], but when running reveal_type(str | int), I get a different long revealed type with overloads that translates to typing.Union | type[str][3].

[1] This relies on a currently unpushed update to my existing changes. I consider it too unfinished to push due to a myriad of internal bugs or violations of expected outputs, such as reveal_type(Union[x, y]) returning Union[x, y] rather than x | y, as is specified in the docstr for mypy.types.TypeStrVisitor that reveal_type relies on.

[2] Overload mess from reveal_type(typing.Union[str, int]):

typing.Union[Overload(def (object: object =) -> str, def (object: _collections_abc.Buffer, encoding: str =, errors: str =) -> str), Overload(def (str | _collections_abc.Buffer | typing.SupportsInt | typing.SupportsIndex =) -> int, def (str | bytes | bytearray, base: typing.SupportsIndex) -> int)]

[3] Overload mess from reveal_type(str | int):

typing.Union | Overload(def (object: object =) -> str, def (object: _collections_abc.Buffer, encoding: str =, errors: str =) -> str)