pytest-dev/pytest · error · ValueError

pytest.param cannot add pytest.mark.usefixtures; see…

Error message

pytest.param cannot add pytest.mark.usefixtures; see https://docs.pytest.org/en/stable/reference/reference.html#pytest-param

What it means

A ValueError raised by ParameterSet.param when any of the supplied marks is named 'usefixtures'. pytest forbids attaching usefixtures through pytest.param because fixture application must be resolved at collection time and pytest.param marks are applied per-parameter-row, which would create ambiguous fixture scoping. The message links to the reference docs.

Solutions

Apply usefixtures at the test function, class, or module level (decorator) instead of via pytest.param.
If you need per-param fixtures, refactor the test so the fixture reads the param value and branches internally.
Use a custom marker and a conftest hook to conditionally request fixtures.

Example fix

# before
@pytest.mark.parametrize('x', [
    pytest.param(1, marks=pytest.mark.usefixtures('db')),
])
def test_x(x): ...
# after
@pytest.mark.usefixtures('db')
@pytest.mark.parametrize('x', [1])
def test_x(x): ...

Defensive patterns

Strategy: validation

Validate before calling

def sanitize_marks(marks):
    return [m for m in marks if getattr(m, 'name', '') != 'usefixtures']

Type guard

def contains_usefixtures(marks) -> bool:
    return any(getattr(m, 'name', '') == 'usefixtures' for m in marks)

Prevention

Never put usefixtures in pytest.param marks.
Apply usefixtures at function/class/module level.
Review mark lists before passing to pytest.param.

When it happens

Trigger: Calling `pytest.param(1, marks=pytest.mark.usefixtures('myfix'))` or passing a tuple of marks containing a usefixtures mark to pytest.param. The check iterates all marks and matches on `.name == 'usefixtures'`.

Common situations: Trying to apply a fixture only to a subset of parametrized values, or refactoring a class-level usefixtures into per-param marks. Copying a mark list that inadvertently includes usefixtures.

Related errors

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

Appendix: source

Thrown at src/_pytest/mark/structures.py:127

    """

    values: Sequence[object | NotSetType]
    marks: Collection[MarkDecorator | Mark]
    id: str | _HiddenParam | None

    @classmethod
    def param(
        cls,
        *values: object,
        marks: MarkDecorator | Collection[MarkDecorator | Mark] = (),
        id: str | _HiddenParam | None = None,
    ) -> ParameterSet:
        if isinstance(marks, MarkDecorator):
            marks = (marks,)
        else:
            assert isinstance(marks, collections.abc.Collection)
        if any(i.name == "usefixtures" for i in marks):
            raise ValueError(
                "pytest.param cannot add pytest.mark.usefixtures; see "
                "https://docs.pytest.org/en/stable/reference/reference.html#pytest-param"
            )

        if id is not None:
            if not isinstance(id, str) and id is not HIDDEN_PARAM:
                raise TypeError(
                    "Expected id to be a string or a `pytest.HIDDEN_PARAM` sentinel, "
                    f"got {type(id)}: {id!r}",
                )
        return cls(values, marks, id)

    @classmethod
    def extract_from(
        cls,
        parameterset: ParameterSet | Sequence[object] | object,
        force_tuple: bool = False,
    ) -> ParameterSet:

View on GitHub (pinned to 0d6fbdeffa)