{"record":{"id":"4772b751e8166470","repo":"Lightning-AI/pytorch-lightning","slug":"to-use-fabric-with-more-than-one-device-you-must","errorCode":null,"errorMessage":"To use Fabric with more than one device, you must call `.launch()` or use the CLI: `fabric run --help`.","messagePattern":"To use Fabric with more than one device, you must call `\\.launch\\(\\)` or use the CLI: `fabric run --help`\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"critical","filePath":"src/lightning/fabric/fabric.py","lineNumber":1195,"sourceCode":"    def _get_distributed_sampler(dataloader: DataLoader, **kwargs: Any) -> DistributedSampler:\n        kwargs.setdefault(\"shuffle\", isinstance(dataloader.sampler, RandomSampler))\n        kwargs.setdefault(\"seed\", int(os.getenv(\"PL_GLOBAL_SEED\", 0)))\n        if isinstance(dataloader.sampler, (RandomSampler, SequentialSampler)):\n            return DistributedSampler(dataloader.dataset, **kwargs)\n        return DistributedSamplerWrapper(dataloader.sampler, **kwargs)\n\n    def _prepare_run_method(self) -> None:\n        if is_overridden(\"run\", self, Fabric) and _is_using_cli():\n            raise TypeError(\n                \"Overriding `Fabric.run()` and launching from the CLI is not allowed. Run the script normally,\"\n                \" or change your code to directly call `fabric = Fabric(...); fabric.setup(...)` etc.\"\n            )\n        # wrap the run method, so we can inject setup logic or spawn processes for the user\n        setattr(self, \"run\", partial(self._wrap_and_launch, self.run))\n\n    def _validate_launched(self) -> None:\n        if not self._launched and not isinstance(self._strategy, (SingleDeviceStrategy, DataParallelStrategy)):\n            raise RuntimeError(\n                \"To use Fabric with more than one device, you must call `.launch()` or use the CLI:\"\n                \" `fabric run --help`.\"\n            )\n\n    def _validate_setup(self, module: nn.Module, optimizers: Sequence[Optimizer]) -> None:\n        self._validate_launched()\n        if isinstance(module, _FabricModule):\n            raise ValueError(\"A model should be passed only once to the `setup` method.\")\n\n        if any(isinstance(opt, _FabricOptimizer) for opt in optimizers):\n            raise ValueError(\"An optimizer should be passed only once to the `setup` method.\")\n\n        if isinstance(self._strategy, FSDPStrategy) and any(\n            _has_meta_device_parameters_or_buffers(optimizer) for optimizer in optimizers\n        ):\n            raise RuntimeError(\n                \"The optimizer has references to the model's meta-device parameters. Materializing them is\"\n                \" is currently not supported unless you to set up the model and optimizer(s) separately.\"","sourceCodeStart":1177,"sourceCodeEnd":1213,"githubUrl":"https://github.com/Lightning-AI/pytorch-lightning/blob/9fed5c27d2a62ff0efd6c3573599921d6ff67c14/src/lightning/fabric/fabric.py#L1177-L1213","documentation":"Collective/parallel operations (setup, barrier, broadcast, all_gather, all_reduce, init_module) require that processes were actually launched. _validate_launched() checks self._launched and allows only SingleDeviceStrategy and DataParallelStrategy through; any distributed strategy used without .launch() (or the CLI) raises RuntimeError.","triggerScenarios":"Fabric(accelerator='gpu', devices=2, strategy='ddp') followed directly by fabric.setup(model) or fabric.all_reduce(tensor) without calling fabric.launch() and without using the `fabric run` CLI.","commonSituations":"Scaling a single-GPU Fabric script to multiple devices by just changing devices=2; forgetting that multi-device Fabric requires a launcher entry point.","solutions":["Wrap training in a function and call fabric.launch(train)","Or launch via CLI: fabric run script.py --devices=2","Or keep devices=1 / single-device strategy if you did not intend to distribute"],"exampleFix":"# before\nfabric = Fabric(devices=2)\nmodel = fabric.setup(model)\n# after\nfabric = Fabric(devices=2)\ndef train(fabric):\n    model = fabric.setup(model)\nfabric.launch(train)","handlingStrategy":"validation","validationCode":"from lightning.fabric.strategies import SingleDeviceStrategy\nfrom lightning.fabric.plugins import DataParallelStrategy\nif fabric._launched or isinstance(fabric.strategy, (SingleDeviceStrategy, DataParallelStrategy)):\n    model = fabric.setup(model)\nelse:\n    fabric.launch(train)","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Multi-device Fabric always needs fabric.launch(fn) or the `fabric run` CLI — structure scripts that way from the start"],"tags":["lightning","fabric","distributed","launch","ddp"],"backgroundTag":"distributed-not-launched","analyzedSha":"9fed5c27d2a62ff0efd6c3573599921d6ff67c14","analyzedAt":"2026-08-28T11:52:41.083Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}