pytest-dev/pytest · error · TypeError

Unexpected keyword arguments passed to pytest.raises: {kwarg

Error message

Unexpected keyword arguments passed to pytest.raises: {kwargs}
Use context-manager form instead?

What it means

Raised by pytest.raises when called in the legacy function-call form (pytest.raises(Exc, func, ...)) and unexpected keyword arguments are passed. The function form only accepts 'match', 'check', and 'expected_exception' as kwargs; anything else triggers this TypeError with a hint to use the context-manager form. The context-manager form (with pytest.raises(Exc) as ...) is the recommended modern usage.

Source

Thrown at src/_pytest/raises.py:262

        help the Python interpreter speed up its garbage collection.

        Clearing those references breaks a reference cycle
        (``ExceptionInfo`` --> caught exception --> frame stack raising
        the exception --> current frame stack --> local variables -->
        ``ExceptionInfo``) which makes Python keep all objects referenced
        from that cycle (including all local variables in the current
        frame) alive until the next cyclic garbage collection run.
        More detailed information can be found in the official Python
        documentation for :ref:`the try statement <python:try>`.
    """
    __tracebackhide__ = True

    if func is None and not args:
        if set(kwargs) - {"match", "check", "expected_exception"}:
            msg = "Unexpected keyword arguments passed to pytest.raises: "
            msg += ", ".join(sorted(kwargs))
            msg += "\nUse context-manager form instead?"
            raise TypeError(msg)

        if expected_exception is None:
            return RaisesExc(**kwargs)
        return RaisesExc(expected_exception, **kwargs)

    if not expected_exception:
        raise ValueError(
            f"Expected an exception type or a tuple of exception types, but got `{expected_exception!r}`. "
            f"Raising exceptions is already understood as failing the test, so you don't need "
            f"any special code to say 'this should never raise an exception'."
        )
    if not callable(func):
        raise TypeError(f"{func!r} object (type: {type(func)}) must be callable")
    with RaisesExc(expected_exception) as excinfo:
        func(*args, **kwargs)
    try:
        return excinfo
    finally:

View on GitHub (pinned to 98b357f69e)

Solutions

Switch to the context-manager form: 'with pytest.raises(ValueError, match=...) as exc_info: func()'.
If using the function form, pass only recognized kwargs (match, check) and pass the callable's own args positionally inside the body.
Remove unrecognized keyword arguments.

Example fix

// before
pytest.raises(ValueError, my_func, unknown=True)
// after
with pytest.raises(ValueError, match="bad") as exc_info:
    my_func(unknown=True)

Defensive patterns

Strategy: validation

Validate before calling

ALLOWED = {"match", "check", "expected_exception"}
bad = set(kwargs) - ALLOWED
if func is None and not args and bad:
    raise TypeError(f"unsupported kwargs: {bad}; use context-manager form")
pytest.raises(ValueError, func, **{k: kwargs[k] for k in kwargs if k in ALLOWED})

Prevention

Use the context-manager form: 'with pytest.raises(Exc) as exc_info:'.
Pass only 'match'/'check' as kwargs to raises.
Pass the callable's own arguments inside the with-block.

When it happens

Trigger: Calling pytest.raises(ValueError, func, foo=bar) where 'foo' is not a recognized kwarg; passing test assertions or extra args meant for the body as kwargs to raises.

Common situations: Mixing up the context-manager and function-call APIs; passing extra arguments that belong to the callable but using the wrong calling convention; old code relying on undocumented kwargs.

Related errors

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