{"record":{"id":"4b45e8426bfc766e","repo":"python/cpython","slug":"category-must-be-a-warning-subclass","errorCode":null,"errorMessage":"category must be a Warning subclass","messagePattern":"category must be a Warning subclass","errorType":"exception","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"Lib/_py_warnings.py","lineNumber":271,"sourceCode":"\ndef filterwarnings(action, message=\"\", category=Warning, module=\"\", lineno=0,\n                   append=False):\n    \"\"\"Insert an entry into the list of warnings filters (at the front).\n\n    'action' -- one of \"error\", \"ignore\", \"always\", \"all\", \"default\", \"module\",\n                or \"once\"\n    'message' -- a regex that the warning message must match\n    'category' -- a class that the warning must be a subclass of\n    'module' -- a regex that the module name must match\n    'lineno' -- an integer line number, 0 matches all warnings\n    'append' -- if true, append to the list of filters\n    \"\"\"\n    if action not in {\"error\", \"ignore\", \"always\", \"all\", \"default\", \"module\", \"once\"}:\n        raise ValueError(f\"invalid action: {action!r}\")\n    if not isinstance(message, str):\n        raise TypeError(\"message must be a string\")\n    if not isinstance(category, type) or not issubclass(category, Warning):\n        raise TypeError(\"category must be a Warning subclass\")\n    if not isinstance(module, str):\n        raise TypeError(\"module must be a string\")\n    if not isinstance(lineno, int):\n        raise TypeError(\"lineno must be an int\")\n    if lineno < 0:\n        raise ValueError(\"lineno must be an int >= 0\")\n\n    if message or module:\n        import re\n\n    if message:\n        message = re.compile(message, re.I)\n    else:\n        message = None\n    if module:\n        module = re.compile(module)\n    else:\n        module = None","sourceCodeStart":253,"sourceCodeEnd":289,"githubUrl":"https://github.com/python/cpython/blob/bc6749cc3b5ae4a5e88a6cc2d5b3bebbe354eae6/Lib/_py_warnings.py#L253-L289","documentation":"Raised by warnings.filterwarnings when category is not a class deriving from Warning. Filters classify warnings by category class, so filterwarnings requires an actual Warning subclass — passing a non-type (an instance) or an unrelated class (e.g. Exception or ValueError) fails this check. Note this site enforces both conditions in one line; the C-accelerated warn() path reports the same condition with a different message.","triggerScenarios":"warnings.filterwarnings('ignore', category=DeprecationWarning()) — passing an instance; category=ValueError or category=Exception (not Warning subclasses); category='DeprecationWarning' (a string); passing the message regex into the category slot by argument mix-up.","commonSituations":"Instantiating the category out of habit; using non-warning exceptions for control flow through the filter API; config-driven category names resolved via getattr on the wrong module; positional-argument mix-ups between message and category.","solutions":["Pass the class itself and make sure it subclasses Warning: category=DeprecationWarning","Resolve string config to the class first: getattr(warnings, name) or importlib, and verify issubclass(cat, Warning)","If you defined a custom category, inherit from Warning (e.g. class MyDep(Warning))","Fix argument order: filterwarnings(action, message_regex, category_class, module_regex, lineno)"],"exampleFix":"# before\nwarnings.filterwarnings('ignore', category=DeprecationWarning())   # instance -> TypeError\nwarnings.filterwarnings('ignore', category=RuntimeError)            # not a Warning -> TypeError\n\n# after\nwarnings.filterwarnings('ignore', category=DeprecationWarning)","handlingStrategy":"type-guard","validationCode":"def is_warning_category(cat) -> bool:\n    return isinstance(cat, type) and issubclass(cat, Warning)\n\nimport warnings\nif not is_warning_category(category):\n    raise TypeError(f'{category!r} is not a Warning subclass')\nwarnings.filterwarnings('ignore', category=category)","typeGuard":"def is_warning_category(cat) -> bool:\n    return isinstance(cat, type) and issubclass(cat, Warning)","tryCatchPattern":null,"preventionTips":["Pass Warning subclasses as classes, never instances or strings","When categories come from config, resolve names to classes and check issubclass(cat, Warning) at parse time","Keep the argument order action, message, category, module, lineno straight to avoid slot mix-ups"],"tags":["warnings","validation","category","filters"],"backgroundTag":null,"analyzedSha":"bc6749cc3b5ae4a5e88a6cc2d5b3bebbe354eae6","analyzedAt":"2026-08-14T22:01:13.976Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}