Lightning-AI/pytorch-lightning · error · ValueError

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

Error message

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

What it means

fabric.setup() wraps a model into a _FabricModule; passing an already-wrapped module again means double setup (re-wrapping, re-sharding, duplicated hooks). _validate_setup detects this via isinstance(module, _FabricModule) and raises ValueError.

Source

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

        if is_overridden("run", self, Fabric) and _is_using_cli():
            raise TypeError(
                "Overriding `Fabric.run()` and launching from the CLI is not allowed. Run the script normally,"
                " or change your code to directly call `fabric = Fabric(...); fabric.setup(...)` etc."
            )
        # wrap the run method, so we can inject setup logic or spawn processes for the user
        setattr(self, "run", partial(self._wrap_and_launch, self.run))

    def _validate_launched(self) -> None:
        if not self._launched and not isinstance(self._strategy, (SingleDeviceStrategy, DataParallelStrategy)):
            raise RuntimeError(
                "To use Fabric with more than one device, you must call `.launch()` or use the CLI:"
                " `fabric run --help`."
            )

    def _validate_setup(self, module: nn.Module, optimizers: Sequence[Optimizer]) -> None:
        self._validate_launched()
        if isinstance(module, _FabricModule):
            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.")

View on GitHub (pinned to 9fed5c27d2)

Solutions

1. Trace where the module was first wrapped and call setup only there
2. Use the returned reference once: model, optimizer = fabric.setup(model, optimizer); for later optimizers use fabric.setup_optimizers(optimizer)

Example fix

# before
model = fabric.setup(model)
model = fabric.setup(model, optimizer)  # second wrap
# after
model, optimizer = fabric.setup(model, optimizer)  # once

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

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

When it happens

Trigger: model = fabric.setup(model) followed by another fabric.setup(model, optimizer) — e.g. in a loop, in a re-entered function, or when setup responsibilities are split across helpers that both call setup.

Common situations: Refactoring so setup runs in two places; retry logic that re-runs setup; calling setup on the return of setup_module.

Related errors

• An optimizer should be passed only once to the `setup` metho
• A model should be passed only once to the `setup_module` met
• The `{type(self._strategy).__name__}` requires the model and
• Received multiple values for {', '.join(duplicated_plugin_ke
• Received both `precision={precision_input}` and `plugins={se

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