Troubleshooting¶
Each section is one diagnostic code: what causes it, how to change the
program, and a program that gives the code with its corrected form. A
diagnostic names the rule it enforces, such as TYP-03; the
language reference explains each rule.
typy explain E0402 prints the section of a code in the terminal.
E0101: source file larger than 16 MiB¶
The main file is over 16 MiB, so TyPy refuses it before reading it (LEX-09). Split the program, or move large data out of the source.
E0102: source file is not valid UTF-8¶
The file holds bytes that are not UTF-8 (LEX-01). Save the file as UTF-8.
E0103: Python syntax error¶
The source is not valid Python for every CPython version from the
program's floor up, 3.12 by default (STD-01), or return, break or
continue is out of place. Fix the syntax CPython would also report, or
write the construct in a form CPython 3.12 accepts.
This program gives E0103:
print("total"
This one is correct:
print("total")
E0104: imaginary literal¶
A literal such as 2j makes a complex, a type TyPy does not have
(LEX-08). Use two float values for the real and imaginary parts.
This program gives E0104:
z = 2j
print(z)
This one is correct:
real, imaginary = 0.0, 2.0
print(real, imaginary)
E0105: source file cannot be read¶
The file named on the command line does not exist or cannot be opened. Check the path and its permissions.
E0106: output file cannot be written¶
TyPy cannot write the executable or the stage output. Check that the
directory exists and can be written, or give another path with -o.
E0107: typy.toml is not valid¶
The project's typy.toml cannot be used: it is not valid TOML, it has a
setting TyPy does not know, a value has the wrong type, such as
python-floor = 3.15 where the string "3.15" is meant, a module path
is not a directory under the project root, version does not start with
a number, or the [allocator] table leaves out one of its three functions
or names one that is not a C function (CLI-07, CLI-12, CLI-13, MEM-08). The diagnostic
points at the line. TyPy exits with status 2 before it reads any module.
Correct the line; the settings are listed in the
command line page.
This typy.toml gives E0107, since the floor is a number:
python-floor = 3.15
This one is correct:
python-floor = "3.15"
E0201: feature planned for a later TyPy release¶
The program uses valid Python that a later TyPy release accepts, such as
a lambda expression or class decorators. The message names the release
and the rule. Write the code without the feature, for example with a
function defined by def, or wait for that release.
This program gives E0201:
largest = lambda a, b: a if a > b else b
print(largest(2, 3))
This one is correct:
def largest(a: int, b: int) -> int:
return a if a > b else b
print(largest(2, 3))
E0202: feature TyPy cannot compile with CPython's meaning¶
The program uses valid Python that TyPy refuses because it cannot give it
CPython's meaning (STD-04), such as global, a class defined inside a
function, or a builtin TyPy does not provide. Restructure the code: pass
values as arguments and return them, and define classes and functions at
the top of the module.
This program gives E0202:
print(eval("1 + 2"))
This one is correct:
print(1 + 2)
E0203: parameter without a type annotation¶
Every parameter except self needs an annotation (TYP-01). Write the
type, such as def area(width: float) -> float:.
This program gives E0203:
def double(n) -> int:
return n * 2
print(double(2))
This one is correct:
def double(n: int) -> int:
return n * 2
print(double(2))
E0204: function without a return annotation¶
Every function needs a return annotation (TYP-01). Write -> None when it
returns nothing. __init__ may leave it out.
This program gives E0204:
def greet(name: str):
print("hello", name)
greet("Ada")
This one is correct:
def greet(name: str) -> None:
print("hello", name)
greet("Ada")
E0205: name is not defined¶
The name is not a variable, function, class or builtin of the program, or an annotation does not name a type. Check the spelling, and define the name before the line that uses it.
This program gives E0205:
total = 3
print(totl)
This one is correct:
total = 3
print(total)
E0206: import of a module TyPy does not provide¶
The program imports a module that neither the program nor TyPy provides
(LIB-08). A module of the program is a .py file, or a package directory
with an __init__.py, under the main file's directory: import tools.text
reads tools/__init__.py and tools/text.py. A relative import such as
from . import helper works only inside a package, as in CPython. For the
standard library, use the modules the message lists, or write the code
without the module.
This program gives E0206:
import json
This one is correct:
values = [1, 2]
print(values)
E0301: is used on values other than None, bool values or class instances¶
is compares identity, which TyPy defines only against None, between
bool and bool | None values, and between instances or type objects
(EXP-08). Compare
other values with ==: CPython's identity of numbers and strings depends
on its caches, so the same program could print different results.
This program gives E0301:
count = 3
print(count is 3)
This one is correct:
count = 3
print(count == 3)
E0302: ** whose result in CPython could have another type¶
CPython's result of x ** y would be a float or a complex for some
values, such as a negative exponent (EXP-04). Write the exponent as a
non-negative integer literal, or use float operands.
This program gives E0302:
def power(base: int, exponent: int) -> int:
return base ** exponent
print(power(2, 3))
This one is correct:
def cube(base: int) -> int:
return base ** 3
print(cube(2))
E0303: and or or with operands of different types¶
and and or return one of their operands, which must have one type
(EXP-09). Make both operands the same type, or use an if statement.
This program gives E0303:
name = ""
print(name or 0)
This one is correct:
name = ""
print(name or "anonymous")
E0304: truth test on a value of an unsupported type¶
The value cannot be tested for truth (EXP-10). Compare it explicitly, such
as count > 0.
This program gives E0304:
from typing import Iterable
def show(values: Iterable[int]) -> None:
if values:
print("some")
This one is correct:
def show(values: list[int]) -> None:
if len(values) > 0:
print("some")
show([1])
E0305: conditional expression with branches of different types¶
x if c else y gives one of two values, which must have one type
(EXP-11). Make both branches the same type.
This program gives E0305:
count = 2
print("many" if count > 1 else count)
This one is correct:
count = 2
print("many" if count > 1 else str(count))
E0306: variable read before it is assigned on every path¶
A variable, a function or a class is read where it may not be assigned
yet, which CPython would report as UnboundLocalError or NameError
(TYP-12). Assign the variable on every path, move a definition or the
import of a function or a class above the statement that uses it, or
quote a class name in an annotation, such as "Node".
This program gives E0306:
for number in range(3):
if number > 1:
last = number
print(last)
This one is correct:
last = -1
for number in range(3):
if number > 1:
last = number
print(last)
E0307: tuple indexed other than by an integer literal inside it¶
Each item of a fixed tuple has its own type, so its position must be a
literal inside the tuple (DAT-08). A variable that holds a union of fixed
tuples takes a literal inside at least one member, and raises IndexError
when the tuple it holds is shorter. Use a literal index, unpack the tuple,
or use tuple[T, ...] when every item has one type.
This program gives E0307:
pair = (1, "one")
position = 0
print(pair[position])
This one is correct:
pair = (1, "one")
number, name = pair
print(number, name)
E0308: unpacking into a different number of targets¶
The value has a different number of items than there are targets (SMT-02). Use as many targets as the tuple has items.
This program gives E0308:
x, y = (1, 2, 3)
print(x, y)
This one is correct:
x, y, z = (1, 2, 3)
print(x, y, z)
E0309: instance used before __init__ assigns every attribute¶
In __init__, self was passed on, a method was called on it, an
attribute was read before it was assigned, or __init__ can end without
assigning an attribute (CLS-01). Assign every attribute on every path
first, then use self.
This program gives E0309:
class Point:
def __init__(self) -> None:
print(self.x)
self.x = 0
Point()
This one is correct:
class Point:
def __init__(self) -> None:
self.x = 0
print(self.x)
Point()
E0310: attribute whose type is not known yet¶
An attribute is read where its type is not known yet, because the
__init__ that assigns it is checked later (CLS-01). Declare the attribute
in the class body, such as value: int.
This program gives E0310:
class Pair:
def __init__(self, other: "Pair | None") -> None:
if other is not None:
print(other.left)
self.left = 1
This one is correct:
class Pair:
left: int
def __init__(self, other: "Pair | None") -> None:
if other is not None:
print(other.left)
self.left = 1
Pair(Pair(None))
E0401: operator not defined for these operand types¶
The operator, method or use does not apply to these types (EXP-02), such
as 1 + "a", or an optional value used before a test shows it is not
None (TYP-13). Convert one operand, such as str(1) + "a", or test the
optional value with if value is not None: first.
This program gives E0401:
print(1 + "a")
This one is correct:
print(str(1) + "a")
E0402: assignment changes the type of a variable¶
A variable or attribute keeps the type of its first value or annotation
(TYP-03). Use a new variable for a value of another type. An int where a
float is declared is also refused (TYP-09): write 1.0.
This program gives E0402:
count = 0
count = "none"
print(count)
This one is correct:
count = 0
label = "none"
print(count, label)
E0403: Any, cast or an untyped value¶
typing.Any, typing.cast and object annotations would leave a value
without one type (TYP-10). Annotate the type the value holds.
This program gives E0403:
value: object = 1
print(value)
This one is correct:
value: int = 1
print(value)
E0404: argument of the wrong type¶
An argument does not match its parameter, an argument is missing or extra, or a keyword names no parameter (TYP-01). Pass a value of the parameter's type.
This program gives E0404:
def double(n: int) -> int:
return n * 2
print(double("2"))
This one is correct:
def double(n: int) -> int:
return n * 2
print(double(int("2")))
E0405: returned value of the wrong type¶
The returned value does not match the return annotation, or a function that returns a value can reach its end without returning (TYP-01). Return a value of the declared type on every path.
This program gives E0405:
def half(n: int) -> int:
return n / 2
print(half(4))
This one is correct:
def half(n: int) -> int:
return n // 2
print(half(4))
E0406: arithmetic on bool¶
True + 1 is valid Python, but TyPy keeps bool and int apart
(DAT-03). Convert with int(flag) first.
This program gives E0406:
done = True
print(done + 1)
This one is correct:
done = True
print(int(done) + 1)
E0407: comparison between unsupported types¶
The two values cannot be compared, such as a str with an int, or
instances ordered with < (EXP-06). Compare values of one type.
This program gives E0407:
print("10" < 9)
This one is correct:
print(int("10") < 9)
E0408: annotation without its item types¶
A tuple, list, set or dict annotation names no item types (TYP-06).
Write them, such as list[int] or dict[str, float].
This program gives E0408:
def total(values: list) -> int:
return sum(values)
print(total([1, 2]))
This one is correct:
def total(values: list[int]) -> int:
return sum(values)
print(total([1, 2]))
E0409: list, set or dict display with items of different types¶
Every item of a display has one type (DAT-07, DAT-09, DAT-10). Make the items one type, or use a tuple for values of different types.
This program gives E0409:
row = [1, "two"]
print(row)
This one is correct:
row = (1, "two")
print(row)
E0410: empty collection without an annotation¶
[], {}, set() and dict() need their item types from an annotation
or from where the value goes (TYP-05). Annotate the variable, such as
names: list[str] = [].
This program gives E0410:
names = []
names.append("Ada")
print(names)
This one is correct:
names: list[str] = []
names.append("Ada")
print(names)
E0411: for over a value that cannot be iterated¶
The loop's source cannot be iterated, or its items would not have one
type, as in a tuple of mixed items (CST-03). Loop over a list or a
tuple[T, ...] of one item type.
This program gives E0411:
for digit in 123:
print(digit)
This one is correct:
for digit in str(123):
print(digit)
E0412: method a built-in type does not have¶
The value's type has no such method or attribute in TyPy (LIB-03). Check the method's name and the value's type.
This program gives E0412:
print("a,b".explode(","))
This one is correct:
print("a,b".split(","))
E0413: set item or dict key of a type without a hash¶
A list, a set, a dict or a tuple that holds one cannot be a set item or a
dict key (DAT-09, DAT-10). Use a tuple, a str or a number as the key.
This program gives E0413:
seen = {[1, 2]}
print(seen)
This one is correct:
seen = {(1, 2)}
print(seen)
E0414: attribute or method a class does not have¶
The class has no attribute or method of that name, and an attribute
cannot be added outside __init__ (CLS-02). Declare the attribute in the
class body or assign it in __init__.
This program gives E0414:
class Point:
def __init__(self) -> None:
self.x = 0
p = Point()
print(p.y)
This one is correct:
class Point:
def __init__(self) -> None:
self.x = 0
p = Point()
print(p.x)
E0415: raise of a value that is not an exception¶
raise and from take an exception, such as ValueError("bad input"),
or an exception class, which is called with no arguments (SMT-06). Raise
an exception, not a message: raise ValueError("bad input") rather than
raise "bad input".
This program gives E0415:
raise "failed"
This one is correct:
try:
raise ValueError("failed")
except ValueError as error:
print(error)
E0416: bare raise outside an except clause¶
A raise with nothing after it raises the exception being handled again,
so it belongs inside an except clause (EXC-07). Elsewhere, name the
exception to raise.
This program gives E0416:
def fail() -> None:
raise
This one is correct:
def fail() -> None:
raise RuntimeError("failed")
try:
fail()
except RuntimeError as error:
print(error)
E0417: exception class a program cannot build¶
UnicodeDecodeError and UnicodeEncodeError take five arguments that
TyPy does not check, so a program cannot call them (EXC-12). It can still
catch them. Raise ValueError or a class of your own instead.
This program gives E0417:
error = UnicodeDecodeError("utf-8", b"", 0, 1, "bad")
This one is correct:
error = ValueError("bad")
print(error)
E0418: except clause that names something other than classes¶
An except clause names one exception class, such as except KeyError:,
or a tuple of them, such as except (KeyError, IndexError): (EXC-09). An
instance, a string or a variable that holds a class is refused. Name the
class itself.
This program gives E0418:
try:
print(1 // 0)
except "zero":
pass
This one is correct:
try:
print(1 // 0)
except ZeroDivisionError:
print("zero")
E0419: return, break or continue that leaves a finally block¶
Leaving a finally block with return, break or continue drops an
exception that is on its way out, so TyPy refuses it, as CPython 3.14
warns about it (EXC-06). Move the statement after the try statement. A
break or continue of a loop inside the finally block is accepted.
This program gives E0419:
def first() -> int:
try:
return 1
finally:
return 2
print(first())
This one is correct:
def first() -> int:
try:
return 1
finally:
print("done")
print(first())
E0420: with on a value without __enter__ and __exit__¶
A with statement needs a context manager: an instance of a class that
defines __enter__ and __exit__ (CST-05). Define both in the class, or
use try and finally for a value that has none.
This program gives E0420:
class Plain:
pass
with Plain():
pass
This one is correct:
class Opened:
def __enter__(self) -> "Opened":
print("enter")
return self
def __exit__(self, kind, value, trace) -> None:
print("exit")
with Opened():
pass
E0421: del of something other than an item, a slice or a key¶
del removes a list item, a list slice or a dict key (SMT-05). A
variable or an attribute stays bound once assigned in TyPy, and a tuple,
a str or bytes cannot change. Assign a new value instead, or keep the
values in a list or a dict.
This program gives E0421:
count = 1
del count
This one is correct:
counts = [1, 2]
del counts[0]
print(counts)
E0422: circular import at module level¶
Two or more modules import each other at module level (MOD-05), so one of them would run while another is half initialised. The message shows each import of the cycle. Move one import into the function that uses the module: an import inside a function runs when the function is called, and makes no cycle.
These two modules give E0422, since each imports the other while it starts:
# main.py
import shapes
# shapes.py
import main
Moving one import into the function that uses it is correct:
# main.py
import shapes
# shapes.py
def draw() -> None:
import main
E0423: global of a name the module does not bind¶
A module variable keeps one type, which the module's own code gives it
(SMT-08), so a function cannot create one with global. Assign the
variable at module level, or declare its type there without a value,
such as total: int.
This program gives E0423:
def reset() -> None:
global total
total = 0
This one is correct:
total = 5
def reset() -> None:
global total
total = 0
reset()
print(total)
E0424: an __init__ reads a module variable before its type is known¶
Each __init__ is checked before the module's code, because the module
reads the attributes it assigns. A module variable whose value needs
those attributes has no type yet when the __init__ reads it. Declare
its type at module level, such as LIMIT: int = c.v.
This program gives E0424:
class Config:
def __init__(self) -> None:
self.limit = 10
class Gauge:
def __init__(self) -> None:
self.ceiling = LIMIT
LIMIT = Config().limit
print(Gauge().ceiling)
This one is correct:
class Config:
def __init__(self) -> None:
self.limit = 10
class Gauge:
def __init__(self) -> None:
self.ceiling = LIMIT
LIMIT: int = Config().limit
print(Gauge().ceiling)
E0425: import of a name its module does not define¶
from m import x and m.x name something the module m defines at
module level: a function, a class, a variable it assigns, or one of its
submodules (SMT-07). Check the spelling, and that m binds the name at
module level rather than inside a function.
With shapes.py holding def area(width: float) -> float, this
main.py gives E0425, since shapes has no volume:
from shapes import volume
Importing a name the module defines is correct:
from shapes import area
E0426: import inside __init__ of a module that imports this one¶
TyPy checks each module after the modules it imports at module level, and
checks a function that imports a module checked later once that module is
(MOD-13). An __init__ is checked first, since it gives the attributes
their types, so when module a imports b at module level, an __init__
of b that imports a cannot see a's names yet; this is planned for
1.0 (MOD-15). Import a in a method other than __init__, or move the
code both modules share into a third module that each imports at module
level.
These two modules give E0426, since shapes imports config at module
level and the __init__ of a class of config imports shapes:
# shapes.py
import config
# config.py
class Settings:
def __init__(self) -> None:
import shapes
self.size = shapes.DEFAULT
Reading the value in a method of its own is correct:
# config.py
class Settings:
def size(self) -> int:
import shapes
return shapes.DEFAULT
E0427: % format that does not fit its values¶
The values of format % values do not fit the format: there are too few
or too many, a conversion gets a value of a type it cannot format, such as
%d of a str, or the format itself is not valid (LIB-10). CPython would
raise TypeError or ValueError for every run of the program, and the
message is CPython's. Give one value for each conversion, of a type it
formats, or use %s, which formats any value.
This program gives E0427:
print("%d of %d done" % (3,))
This one is correct:
print("%d of %d done" % (3, 4))
E0428: copies of a generic function without end¶
A generic function calls itself with a larger type each time, as f(x)
calling f([x]). TyPy compiles one copy of a generic function for each
set of types it is called with (GEN-03, ADR-0023), and each copy here
needs a copy for a larger type, so the copies would never end; past 64
copies inside one another the program is refused. Call the function with
the same type, or write the recursion over a type that does not grow.
This program gives E0428:
def depth[T](value: T, levels: int) -> int:
if levels == 0:
return 0
return depth([value], levels - 1) + 1
print(depth(1, 3))
This one is correct:
def depth[T](value: list[T], levels: int) -> int:
if levels == 0:
return 0
return depth(value, levels - 1) + 1
print(depth([1], 3))
E0429: module or export that a C library cannot have¶
A module built with typy build --lib exports the functions its __all__
lists, each as a C function (FFI-05). This error names what cannot be one:
- the module has no
__all__, binds it more than once, or binds it to something other than a list or tuple of string literals; - a name is not a function the module defines with
defat its top level, or is generic; - a parameter or the result has a type other than
int,floatorbool, orNonefor the result; - the name is not ASCII, starts with
__,_and a capital letter, ortypy_, is listed twice, or is a C function the library itself calls, such asread,free,sqrtormain, or one of the project's allocator functions; - the file's name is not an ASCII identifier, which the library and its header are named after (CLI-09);
__version__is not one string literal that starts with a number, or differs fromversionintypy.toml(CLI-13).
Rename the function, or export one of C types that calls it. This module
is a correct program, but built with --lib it gives E0429 for label,
whose result is a str:
__all__ = ["label"]
def label(number: int) -> str:
return "item " + str(number)
This one exports a function of C types instead:
__all__ = ["label_length"]
def label(number: int) -> str:
return "item " + str(number)
def label_length(number: int) -> int:
return len(label(number))
E0430: ctypes declaration TyPy cannot compile¶
TyPy compiles a program's ctypes declarations into direct calls when it
builds the program, so it reads them from the module's statements
(FFI-01 to FFI-03, ADR-0047). This error names a declaration it cannot
read that way:
- a library named other than by one string literal, or loaded other than at module level and bound to a name;
argtypesassigned something other than a list or tuple ofctypestypes,restypesomething other than actypestype orNone, or either assigned twice;- a
ctypestype TyPy does not compile, such asc_char; - a function called without both its
argtypesand itsrestype, or called at module level before them.
Declare each library and function once, at module level, before the
first call at module level. This program gives E0430, since the function
is called before its restype is assigned:
import ctypes
libc = ctypes.CDLL("libc.so.6")
libc.abs.argtypes = [ctypes.c_int]
print(libc.abs(-3))
libc.abs.restype = ctypes.c_int
This one is correct:
import ctypes
libc = ctypes.CDLL("libc.so.6")
libc.abs.argtypes = [ctypes.c_int]
libc.abs.restype = ctypes.c_int
print(libc.abs(-3))
E0701: C toolchain program not found¶
TyPy links programs with the system C toolchain, which is not installed
(A-01). Install it, such as sudo apt install build-essential.
E0702: link failed¶
The C toolchain could not link the program (A-01). The message shows the
linker's output; check that the toolchain works with cc --version.
When the output says cannot find -lNAME, the linker did not find the
library that library in the [allocator] table of typy.toml names
(MEM-08). Install the library, or tell the linker where it is with
LIBRARY_PATH:
LIBRARY_PATH=$PWD/lib typy build app.py
E0703: runtime archive missing, or from another TyPy version¶
The runtime library TyPy links into programs is not beside the typy
command, or comes from another version. Unpack the release archive again
and run its own bin/typy.
E9001: internal compiler error¶
TyPy itself failed. This is a defect in TyPy: please report it with the program that caused it.
W0101: invalid escape sequence¶
A string or bytes literal holds a backslash before a character that does
not start an escape, such as "\d", or an octal escape above \377.
CPython keeps the backslash and warns while compiling, and so does TyPy
(DIA-08). Write the backslash twice, "\\d", which keeps the same value
and which the diagnostic shows, or use a raw string, r"\d".
This program gives W0101 and still runs:
print("\d+ digits")
This one is correct:
print("\\d+ digits")
W0401: match leaves members of its subject's type unmatched¶
The subject's type is a union, an optional or a bool, and no case
without a guard matches every value of some of its members, which the
warning names (CST-07, ADR-0033). The program builds and runs; a subject
no case matches skips the match. Add a case for each member, or end
with case _: when the rest need nothing. Here the warning names None.
This program gives W0401 and still runs:
def describe(code: int | None) -> str:
match code:
case int(number):
return f"code {number}"
return "no code"
print(describe(None))
This one is correct:
def describe(code: int | None) -> str:
match code:
case int(number):
return f"code {number}"
case None:
return "no code"
print(describe(None))
Its cases cover every value, so the function needs no return after the
match. A case with a guard covers nothing, since the guard may be false,
and a set of cases that covers a member only together, such as case []:
and case [first, *rest]: for a list, needs case _: as well.
W0301: assertion that is always true¶
assert (test, "message") asserts a tuple with two items, which is always
true, so the assertion never fails (DIA-08). Remove the parentheses:
assert test, "message".
This program gives W0301 and still runs:
count = 0
assert (count == 0, "count starts at zero")
This one is correct:
count = 0
assert count == 0, "count starts at zero"