Lightning-AI/pytorch-lightning · error · ValueError

A model should be passed only once to the `setup_module` met

Error message

A model should be passed only once to the `setup_module` method.

What it means

setup_module() is the model-only variant of setup(); passing a module that is already a _FabricModule means it was already wrapped, and re-wrapping would corrupt strategy state. _validate_setup_module raises ValueError on the isinstance check.

Source

Thrown at src/lightning/fabric/fabric.py:1221

            raise ValueError("A model should be passed only once to the `setup` method.")

        if any(isinstance(opt, _FabricOptimizer) for opt in optimizers):
            raise ValueError("An optimizer should be passed only once to the `setup` method.")

        if isinstance(self._strategy, FSDPStrategy) and any(
            _has_meta_device_parameters_or_buffers(optimizer) for optimizer in optimizers
        ):
            raise RuntimeError(
                "The optimizer has references to the model's meta-device parameters. Materializing them is"
                " is currently not supported unless you to set up the model and optimizer(s) separately."
                " Create and set up the model first through `model = fabric.setup_module(model)`. Then create the"
                " optimizer and set it up: `optimizer = fabric.setup_optimizers(optimizer)`."
            )

    def _validate_setup_module(self, module: nn.Module) -> None:
        self._validate_launched()
        if isinstance(module, _FabricModule):
            raise ValueError("A model should be passed only once to the `setup_module` method.")

    def _validate_setup_optimizers(self, optimizers: Sequence[Optimizer]) -> None:
        self._validate_launched()
        if isinstance(self._strategy, (DeepSpeedStrategy, XLAStrategy)):
            raise RuntimeError(
                f"The `{type(self._strategy).__name__}` requires the model and optimizer(s) to be set up jointly"
                " through `.setup(model, optimizer, ...)`."
            )

        if not optimizers:
            raise ValueError("`setup_optimizers` requires at least one optimizer as input.")

        if any(isinstance(opt, _FabricOptimizer) for opt in optimizers):
            raise ValueError("An optimizer should be passed only once to the `setup_optimizers` method.")

        if any(_has_meta_device_parameters_or_buffers(optimizer) for optimizer in optimizers):
            raise RuntimeError(
                "The optimizer has references to the model's meta-device parameters. Materializing them is"

View on GitHub (pinned to 9fed5c27d2)

Solutions

1. Call setup_module exactly once and reuse its return value
2. If the module came from setup(model, optimizer), do not set it up again — only set up remaining pieces

Example fix

# before
model = fabric.setup_module(model)
model = fabric.setup_module(model)  # re-wrap
# after
model = fabric.setup_module(model)  # once

from lightning.fabric.wrappers import _FabricModule
assert not isinstance(model, _FabricModule), 'module already set up'

from lightning.fabric.wrappers import _FabricModule
def module_needs_setup(m):
    return not isinstance(m, _FabricModule)

When it happens

Trigger: Calling fabric.setup_module(model) twice, or calling setup_module on the output of fabric.setup(model, optimizer) (which also returns a _FabricModule).

Common situations: Mixing setup() and setup_module() in one script; checkpoint-resume code that re-runs the module setup path.

Related errors

• A model should be passed only once to the `setup` method.
• An optimizer should be passed only once to the `setup` metho
• Received multiple values for {', '.join(duplicated_plugin_ke
• Received both `precision={precision_input}` and `plugins={se
• accelerator set through both strategy class and accelerator

AI-assisted analysis of Lightning-AI/pytorch-lightning@9fed5c27d2 (2026-08-28). Data as JSON: /api/errors/ebc46fe294c0fa3b. Report an issue: GitHub.