{"id":"fc099e9a229a78aa","repo":"pytest-dev/pytest","slug":"cat-is-not-a-warning-subclass","errorCode":null,"errorMessage":"{cat} is not a Warning subclass","messagePattern":"(.+?) is not a Warning subclass","errorType":"exception","errorClass":"UsageError","httpStatus":null,"severity":"error","filePath":"src/_pytest/config/__init__.py","lineNumber":2344,"sourceCode":"def _resolve_warning_category(category: str) -> type[Warning]:\n    \"\"\"\n    Copied from warnings._getcategory, but changed so it lets exceptions (specially ImportErrors)\n    propagate so we can get access to their tracebacks (#9218).\n    \"\"\"\n    __tracebackhide__ = True\n    if not category:\n        return Warning\n\n    if \".\" not in category:\n        import builtins as m\n\n        klass = category\n    else:\n        module, _, klass = category.rpartition(\".\")\n        m = importlib.import_module(module)\n    cat = getattr(m, klass)\n    if not issubclass(cat, Warning):\n        raise UsageError(f\"{cat} is not a Warning subclass\")\n    return cast(type[Warning], cat)\n\n\ndef apply_warning_filters(\n    config_filters: Iterable[str], cmdline_filters: Iterable[str]\n) -> None:\n    \"\"\"Applies pytest-configured filters to the warnings module\"\"\"\n    # Filters should have this precedence: cmdline options, config.\n    # Filters should be applied in the inverse order of precedence.\n    for arg in config_filters:\n        try:\n            warnings.filterwarnings(*parse_warning_filter(arg, escape=False))\n        except ImportError as e:\n            warnings.warn(\n                f\"Failed to import filter module '{e.name}': {arg}\", PytestConfigWarning\n            )\n            continue\n","sourceCodeStart":2326,"sourceCodeEnd":2362,"githubUrl":"https://github.com/pytest-dev/pytest/blob/98b357f69e380da908740a212288d73b2ee06687/src/_pytest/config/__init__.py#L2326-L2362","documentation":"Pytest raises this UsageError when the category field of a warning filter resolves via import/getattr to an object that is not a subclass of the built-in Warning class. Warning filters require the category to be an actual Warning subclass (or the empty string, which defaults to Warning).","triggerScenarios":"A filter like 'ignore::os.path' where os.path is not a Warning subclass, or 'ignore::collections.OrderedDict'. _resolve_warning_category successfully imports and gets the attribute, but issubclass(cat, warning) is False.","commonSituations":"Pointing the category at a regular exception or arbitrary class by mistake; referring to a class that was renamed from a Warning to a non-Warning; copy-paste errors swapping the category and module fields.","solutions":["Ensure the referenced class subclasses Warning (e.g. class MyWarning(Warning): ...).","Use a stdlib warning like DeprecationWarning, UserWarning, ResourceWarning, or bare Warning.","Double-check field order: the 3rd field is the category, not the module."],"exampleFix":"# before\n[pytest]\nfilterwarnings = [\"ignore::builtins.ValueError\"]\n\n# after\n[pytest]\nfilterwarnings = [\"ignore::builtins.DeprecationWarning\"]","handlingStrategy":"type-guard","validationCode":"import importlib, warnings\ndef resolve_and_check_category(category: str) -> type:\n    if not category:\n        return Warning\n    if '.' not in category:\n        import builtins\n        cat = getattr(builtins, category)\n    else:\n        module, _, klass = category.rpartition('.')\n        cat = getattr(importlib.import_module(module), klass)\n    if not (isinstance(cat, type) and issubclass(cat, warnings.Warning)):\n        raise TypeError(f'{cat} is not a Warning subclass')\n    return cat","typeGuard":"import warnings\ndef is_warning_subclass(obj: object) -> bool:\n    return isinstance(obj, type) and issubclass(obj, warnings.Warning)","tryCatchPattern":null,"preventionTips":["Define custom warnings as subclasses of Warning (or a stdlib warning).","Add a unit test asserting issubclass(MyWarning, Warning).","Prefer stdlib categories when a custom subclass isn't required."],"tags":["pytest","config","warnings","filterwarnings","type-check","usage-error"],"analyzedSha":"98b357f69e380da908740a212288d73b2ee06687","analyzedAt":"2026-08-04T20:26:34.442Z","schemaVersion":2}