Skip to content

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 def at its top level, or is generic;
  • a parameter or the result has a type other than int, float or bool, or None for the result;
  • the name is not ASCII, starts with __, _ and a capital letter, or typy_, is listed twice, or is a C function the library itself calls, such as read, free, sqrt or main, 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 from version in typy.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;
  • argtypes assigned something other than a list or tuple of ctypes types, restype something other than a ctypes type or None, or either assigned twice;
  • a ctypes type TyPy does not compile, such as c_char;
  • a function called without both its argtypes and its restype, 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.

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"