What causes "You must specify at least one parameter to match on." in pytest-dev/pytest?

Supply at least one argument: the exception type, a match regex, or a check callable.

pytest-dev/pytest · error · ValueError

You must specify at least one parameter to match on.

Error message

You must specify at least one parameter to match on.

What it means

Raised by RaisesExc.__init__ when none of expected_exception, match, or check is supplied. RaisesExc needs at least one matching criterion to be meaningful; an empty matcher would match any exception and is almost always a bug. The guard runs after tuple/None normalization, so RaisesExc() with all defaults triggers it.

Solutions

Supply at least one argument: the exception type, a match regex, or a check callable.
In helper code, default the missing parameter explicitly (e.g. expected_exception=ValueError) rather than leaving it None.
If you intend 'match anything', use RaisesExc(BaseException) to make that intent explicit.

Example fix

// before
matcher = RaisesExc()  # ValueError
// after
matcher = RaisesExc(ValueError)
// or express intent explicitly:
matcher = RaisesExc(BaseException)

Defensive patterns

Strategy: validation

Validate before calling

assert expected_exception is not None or match is not None or check is not None, 'RaisesExc needs an exception, match, or check'

Type guard

def raisesexc_has_criterion(expected_exception, match, check) -> bool:
    return expected_exception is not None or match is not None or check is not None

Prevention

Always supply at least one of expected_exception, match, or check when building RaisesExc.
In helpers that forward parameters, default expected_exception to a sensible type rather than None.
Document RaisesExc construction at the call site.

When it happens

Trigger: Constructing RaisesExc() with no arguments; RaisesExc(None); or RaisesExc(()) where match and check are also None. The check is `(expected_exceptions == ()) and match is None and check is None`.

Common situations: Building RaisesExc objects programmatically (e.g. in a fixture or helper) and forgetting to forward a parameter; refactor that drops the exception type while leaving match/check unset; conditional construction that leaves all three empty on a branch.

Related errors

AI-assisted analysis of pytest-dev/pytest@0d6fbdeffa (2026-08-11). Data as JSON: /api/errors/c8d251cb9d51b659. Report an issue: GitHub.

Appendix: source

Thrown at src/_pytest/raises.py:622

        self,
        expected_exception: (
            type[BaseExcT_co_default] | tuple[type[BaseExcT_co_default], ...] | None
        ) = None,
        /,
        *,
        match: str | Pattern[str] | None = None,
        check: Callable[[BaseExcT_co_default], bool] | None = None,
    ):
        super().__init__(match=match, check=check)
        if isinstance(expected_exception, tuple):
            expected_exceptions = expected_exception
        elif expected_exception is None:
            expected_exceptions = ()
        else:
            expected_exceptions = (expected_exception,)

        if (expected_exceptions == ()) and match is None and check is None:
            raise ValueError("You must specify at least one parameter to match on.")

        self.expected_exceptions = tuple(
            self._parse_exc(e, expected="a BaseException type")
            for e in expected_exceptions
        )

        self._just_propagate = False

    def matches(
        self,
        exception: BaseException | None,
    ) -> TypeGuard[BaseExcT_co_default]:
        """Check if an exception matches the requirements of this :class:`RaisesExc`.
        If it fails, :attr:`RaisesExc.fail_reason` will be set.

        Examples::

            assert RaisesExc(ValueError).matches(my_exception):

View on GitHub (pinned to 0d6fbdeffa)