#2172·jinja

FilterArgumentError exception is not documented and not in the "jinja2" module

Author: andy-maierCreated May 16, 2026Updated May 16, 2026

The documentation at https://jinja.palletsprojects.com/en/stable/ documents all public exceptions in the jinja2.exceptions module, except for FilterArgumentError.

When I ask Claude what exception should be returned from Jinja2 filters in case of invalid arguments, it refers to FilterArgumentError.

When I scan the filters provided by Jinja2 itself for what they return in case of invalid arguments, it is FilterArgumentError.

I do realize that there is an asymmetry between filter and test plugins w.r.t. this exception (i.e. there is no TestArgumentError), and Ansible has similar asymmetries between filters and tests.

However, I think from a pragmatic and compatibility perspective, FilterArgumentError should be treated as a first class citizen exception, and should be documented and made visible in the jinja2 top level module.