Lightning-AI/pytorch-lightning · error · TypeError

Overriding `Fabric.run()` and launching from the CLI is not

Error message

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.

What it means

In __init__, Fabric wraps self.run to inject setup/spawn logic. If a subclass overrides run() AND the script was started through the CLI, the wrapping would silently bypass the override, so Fabric raises TypeError telling you to either run normally or not rely on overriding run().

Source

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

    def _requires_distributed_sampler(self, dataloader: DataLoader) -> bool:
        return (
            getattr(self.strategy, "distributed_sampler_kwargs", None) is not None
            and not isinstance(dataloader.sampler, DistributedSampler)
            and not has_iterable_dataset(dataloader)
        )

    @staticmethod
    def _get_distributed_sampler(dataloader: DataLoader, **kwargs: Any) -> DistributedSampler:
        kwargs.setdefault("shuffle", isinstance(dataloader.sampler, RandomSampler))
        kwargs.setdefault("seed", int(os.getenv("PL_GLOBAL_SEED", 0)))
        if isinstance(dataloader.sampler, (RandomSampler, SequentialSampler)):
            return DistributedSampler(dataloader.dataset, **kwargs)
        return DistributedSamplerWrapper(dataloader.sampler, **kwargs)

    def _prepare_run_method(self) -> None:
        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.")

View on GitHub (pinned to 9fed5c27d2)

Solutions

1. Run the script with plain `python script.py` instead of the CLI
2. Or remove the run() override and put logic in your launched function or the CLI-invoked flow

Example fix

# before
class MyFabric(Fabric):
    def run(self): ...  # + launched via `fabric run`
# after
python script.py  # run normally, override allowed

# If you override run(), launch with plain python, not the CLI
# python script.py  (not: fabric run script.py)

When it happens

Trigger: Subclassing Fabric and defining a run() method, then executing the script with `fabric run ...`. is_overridden('run', self, Fabric) combined with _is_using_cli() triggers it in __init__.

Common situations: Porting a custom Fabric subclass from standalone scripts to the CLI workflow; overriding run() to add hooks.

Related errors

• This script was launched through the CLI, and processes have
• Received multiple values for {', '.join(duplicated_plugin_ke
• Received both `precision={precision_input}` and `plugins={se
• accelerator set through both strategy class and accelerator
• precision set through both strategy class and plugins, choos

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