python/cpython · error · ValueError

lineno must be an int >= 0

Error message

lineno must be an int >= 0

What it means

Raised by warnings.filterwarnings when lineno is an int but negative. Line numbers in filter entries must be >= 0, with 0 meaning 'match warnings on any line'; a negative value never matches anything and almost certainly signals a computation bug, so it is rejected with ValueError.

Source

Thrown at Lib/_py_warnings.py:277

                or "once"
    'message' -- a regex that the warning message must match
    'category' -- a class that the warning must be a subclass of
    'module' -- a regex that the module name must match
    'lineno' -- an integer line number, 0 matches all warnings
    'append' -- if true, append to the list of filters
    """
    if action not in {"error", "ignore", "always", "all", "default", "module", "once"}:
        raise ValueError(f"invalid action: {action!r}")
    if not isinstance(message, str):
        raise TypeError("message must be a string")
    if not isinstance(category, type) or not issubclass(category, Warning):
        raise TypeError("category must be a Warning subclass")
    if not isinstance(module, str):
        raise TypeError("module must be a string")
    if not isinstance(lineno, int):
        raise TypeError("lineno must be an int")
    if lineno < 0:
        raise ValueError("lineno must be an int >= 0")

    if message or module:
        import re

    if message:
        message = re.compile(message, re.I)
    else:
        message = None
    if module:
        module = re.compile(module)
    else:
        module = None

    _wm._add_filter(action, message, category, module, lineno, append=append)


def simplefilter(action, category=Warning, lineno=0, append=False):
    """Insert a simple entry into the list of warnings filters (at the front).

View on GitHub (pinned to bc6749cc3b)

Solutions

1. Use 0 to match all lines, or the exact positive line number
2. Clamp/validate computed values: lineno = max(0, computed)
3. Replace -1 sentinels with 0 or omit the argument

Example fix

# before
warnings.filterwarnings('ignore', lineno=match.start - offset)  # can be -1 -> ValueError

# after
warnings.filterwarnings('ignore', lineno=max(0, match.start - offset))

def as_lineno(value) -> int:
    if value is None:
        return 0
    value = int(value)
    if value < 0:
        return 0  # or raise, per your policy
    return value

import warnings
warnings.filterwarnings('ignore', lineno=as_lineno(computed))

def is_valid_lineno(v) -> bool:
    return isinstance(v, int) and not isinstance(v, bool) and v >= 0

When it happens

Trigger: warnings.filterwarnings('ignore', lineno=-1); lineno computed as lineno_of_match - offset that underflows; sentinel values like -1 passed to mean 'none'.

Common situations: Using -1 as a 'not set' sentinel from C-style code; arithmetic on line numbers (e.g. frame.f_lineno - 2) that can go below zero; config validation that accepts negatives.

Related errors

• lineno must be an int
• invalid action: {action!r}
• message must be a string
• category must be a Warning subclass
• module must be a string

AI-assisted analysis of python/cpython@bc6749cc3b (2026-08-14). Data as JSON: /api/errors/bffe38b5bcb822c0. Report an issue: GitHub.