specialtypes_never error

-> NoReturn / -> Never function can fall through

A function declared with a return type of NoReturn or Never must unconditionally raise an exception or call another NoReturn function on every code path. If the function can reach the end of its body without raising (e.g. via an if without an else), the annotation is wrong.

import sys
from typing import NoReturn

def stop() -> NoReturn:         # OK — always raises
    raise RuntimeError("no way")

def bad(x: int) -> NoReturn:    # E — can fall through when x == 0
    if x != 0:
        sys.exit(1)

## Conservative scope

The check is conservative: it only flags a function when **all** of the following hold:

1. The declared return type is exactly NoReturn or Never (checked by extracting the annotation text from the span). 2. The function body is not a stub (... or pass). 3. The last top-level statement is **not** a raise statement and is **not** a standalone call expression (which may itself be NoReturn).

This avoids false positives for valid patterns such as raise RuntimeError(...) or sys.exit(1) as the terminating statement.

How to handle it

Every rule is on by default — strict is the default, not a cage. You can dial specialtypes_never down per-file or per-path from your editor or pyproject.toml, or fix the code so it type-checks. See the Type System rules and the complete diagnostic reference.

Canonical URL: https://www.basilisk-python.dev/errors/specialtypes_never