pytest-dev/pytest · error · UsageError

while parsing the following warning configuration: {arg}

Error message

while parsing the following warning configuration:

  {arg}

This error occurred:

{error}

What it means

Raised by parse_warning_filter (config/__init__.py:2246-2284) when a -W / filterwarnings entry splits into more than 5 colon-separated fields. The expected shape is action:message:category:module:lineno (at most 5 fields); excess colons (e.g. a module path with '::' or a message containing ':') push the count over and the entry is reported verbatim in a UsageError.

Source

Thrown at src/_pytest/config/__init__.py:2284

        {{error}}
        """
    )

    parts = arg.split(":")
    if len(parts) > 5:
        doc_url = (
            "https://docs.python.org/3/library/warnings.html#describing-warning-filters"
        )
        error = dedent(
            f"""\
            Too many fields ({len(parts)}), expected at most 5 separated by colons:

              action:message:category:module:line

            For more information please consult: {doc_url}
            """
        )
        raise UsageError(error_template.format(error=error))

    while len(parts) < 5:
        parts.append("")
    action_, message, category_, module, lineno_ = (s.strip() for s in parts)
    try:
        action: warnings._ActionKind = warnings._getaction(action_)  # type: ignore[attr-defined]
    except warnings._OptionError as e:
        raise UsageError(error_template.format(error=str(e))) from None
    try:
        category: type[Warning] = _resolve_warning_category(category_)
    except ImportError:
        raise
    except Exception:
        exc_info = ExceptionInfo.from_current()
        exception_text = exc_info.getrepr(style="native")
        raise UsageError(error_template.format(error=exception_text)) from None
    if message and escape:
        message = re.escape(message)

View on GitHub (pinned to 98b357f69e)

Solutions

1. Limit the filter to at most 5 colon-separated fields: action:message:category:module:lineno.
2. Remove extra colons in module paths (use dotted form, e.g. mypackage.sub not mypackage::sub).
3. If the message must contain a colon, place it in a field that is matched by substring or use a regex via action 'default' carefully — or move the filter into code via warnings.filterwarnings.
4. Re-read the error block: it echoes the exact failing entry for easy correction.

Example fix

# before
pytest -W 'default::DeprecationWarning:mypkg::sub:extra'

# after
pytest -W 'default::DeprecationWarning:mypkg.sub'

def validate_warning_filter(arg: str):
    if len(arg.split(':')) > 5:
        raise ValueError(
            f'warning filter has {len(arg.split(":"))} fields; max 5: '
            'action:message:category:module:lineno'
        )
    return arg

def is_well_formed_filter(arg: str) -> bool:
    return len(arg.split(':')) <= 5

try:
    pytest.main(['-W', arg])
except Exception:
    # rewrite the filter to <=5 fields and retry

When it happens

Trigger: Passing -W 'default::DeprecationWarning:mypackage::sub' (extra colons) or a filterwarnings entry whose message/module text contains unescaped colons. pytest splits on ':' and counts parts.

Common situations: Filter strings copied from Python docs with extra separators; module paths containing '::'; messages with embedded colons; misusing the lineno field by appending trailing segments.

Related errors

• number is negative
• invalid lineno {lineno_!r}: {e}
• Invalid regex {e.pattern!r}: {e}
• {cat} is not a Warning subclass
• unknown capturing method: {method!r}

AI-assisted analysis of pytest-dev/pytest@98b357f69e (2026-08-04). Data as JSON: /data/errors/a2355e4ed33384c8.json. Report an issue: GitHub.