pytest-dev/pytest · error · ValueError

You cannot specify a nested structure inside a RaisesGroup w

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

flatten_subgroups=True flattens any nested subgroups in the raised group before matching, so specifying a nested RaisesGroup structure in the expectation would be contradictory — the flattened reality could never match a nested expectation.

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 98b357f69e)

Solutions

1. Remove flatten_subgroups if you genuinely want to assert the nested structure.
2. Remove the inner RaisesGroup and list the leaf exceptions flatly: RaisesGroup(ValueError, flatten_subgroups=True).
3. Pick one strategy: either specify full nesting (no flatten) or ignore nesting (flatten + flat expectations).

Example fix

// before
RaisesGroup(RaisesGroup(ValueError), flatten_subgroups=True)
// after
RaisesGroup(ValueError, flatten_subgroups=True)

has_nested = any(isinstance(e, RaisesGroup) for e in expected)
if flatten_subgroups and has_nested:
    raise ValueError('flatten_subgroups conflicts with nested RaisesGroup expectations')
RaisesGroup(*expected, flatten_subgroups=flatten_subgroups)

When it happens

Trigger: Calling RaisesGroup(RaisesGroup(ValueError), flatten_subgroups=True). Hits raises.py:1016 in _parse_excgroup.

Common situations: Developer enables flatten_subgroups to tolerate arbitrary nesting but still encodes a nested expectation; misunderstanding the flattening semantics.

Related errors

• You cannot specify multiple exceptions with `allow_unwrapped
• `allow_unwrapped=True` has no effect when expecting a `Raise
• `allow_unwrapped=True` bypasses the `match` and `check` para
• Expected {expected}, but got {type(exc).__name__!r}. RaisesG
• absolute tolerance can't be NaN.

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