pytest-dev/pytest · error · ValueError

You cannot specify a nested structure inside a RaisesGroup…

Error message

You cannot specify a nested structure inside a RaisesGroup with `flatten_subgroups=True`. The parameter will flatten subgroups in the raised exceptiongroup before matching, which would never match a nested structure.

What it means

Raised by RaisesGroup._parse_excgroup when a nested RaisesGroup appears among expected exceptions while flatten_subgroups=True is set on the outer RaisesGroup. flatten_subgroups flattens subgroups in the raised group before matching, so any nested structure in the expected matcher could never align with the flattened shape — the assertion would be unsatisfiable. pytest rejects this contradiction early.

Solutions

  1. Remove flatten_subgroups=True so the nested RaisesGroup matcher can compare structure-for-structure.
  2. Keep flatten_subgroups=True and flatten the expected matcher too — list leaf exceptions directly: RaisesGroup(ValueError) instead of RaisesGroup(RaisesGroup(ValueError)).
  3. Use RaisesExc leaves only and let flatten_subgroups treat the whole group as a flat list.

Example fix

// before
with pytest.raises(RaisesGroup(RaisesGroup(ValueError), flatten_subgroups=True)):
    ...
// after (flatten both sides):
with pytest.raises(RaisesGroup(ValueError, flatten_subgroups=True)):
    ...
// or keep structure on both sides:
with pytest.raises(RaisesGroup(RaisesGroup(ValueError))):
    ...
Defensive patterns

Strategy: validation

Validate before calling

from _pytest.raises import RaisesGroup
if flatten_subgroups:
    exs = expected_exception if isinstance(expected_exception, tuple) else (expected_exception,)
    assert not any(isinstance(e, RaisesGroup) for e in exs), 'flatten_subgroups conflicts with nested RaisesGroup'

Type guard

def flatten_subgroups_no_nested(expected_exception, flatten_subgroups) -> bool:
    from _pytest.raises import RaisesGroup
    if not flatten_subgroups:
        return True
    exs = expected_exception if isinstance(expected_exception, tuple) else (expected_exception,)
    return not any(isinstance(e, RaisesGroup) for e in exs)

Prevention

When it happens

Trigger: RaisesGroup(RaisesGroup(ValueError), flatten_subgroups=True); any nested RaisesGroup argument combined with flatten_subgroups=True on the parent. The `case RaisesGroup() if self.flatten_subgroups` arm fires.

Common situations: Enabling flatten_subgroups to tolerate subgroup nesting, then also specifying a nested RaisesGroup expectation; refactoring that adds flatten_subgroups without removing nested matchers.

Related errors

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

Appendix: source

Thrown at src/_pytest/raises.py:1016

                expected_exception,
                *other_exceptions,
            )
        )

    def _parse_excgroup(
        self,
        exc: (
            type[BaseExcT_co]
            | types.GenericAlias
            | RaisesExc[BaseExcT_1]
            | RaisesGroup[BaseExcT_2]
        ),
        expected: str,
    ) -> type[BaseExcT_co] | RaisesExc[BaseExcT_1] | RaisesGroup[BaseExcT_2]:
        # verify exception type and set `self.is_baseexception`
        match exc:
            case RaisesGroup() if self.flatten_subgroups:
                raise ValueError(
                    "You cannot specify a nested structure inside a RaisesGroup with"
                    " `flatten_subgroups=True`. The parameter will flatten subgroups"
                    " in the raised exceptiongroup before matching, which would never"
                    " match a nested structure.",
                )
            case RaisesGroup() | RaisesExc():
                self.is_baseexception |= exc.is_baseexception
                exc._nested = True
                return exc
            case tuple():
                raise TypeError(
                    f"Expected {expected}, but got {type(exc).__name__!r}.\n"
                    "RaisesGroup does not support tuples of exception types when expecting one of "
                    "several possible exception types like RaisesExc.\n"
                    "If you meant to expect a group with multiple exceptions, list them as separate arguments."
                )
            case _:
                return super()._parse_exc(exc, expected)

View on GitHub (pinned to 0d6fbdeffa)