{"record":{"id":"aad5029d46d054af","repo":"Lightning-AI/pytorch-lightning","slug":"post-localsgd-algorithm-is-used-but-model-averagi","errorCode":null,"errorMessage":"Post-localSGD algorithm is used, but model averaging period is not provided to DDP strategy.","messagePattern":"Post-localSGD algorithm is used, but model averaging period is not provided to DDP strategy\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/lightning/pytorch/strategies/ddp.py","lineNumber":250,"sourceCode":"        rank_zero_only.rank = utils_rank_zero_only.rank = self.global_rank\n\n    def _register_ddp_hooks(self) -> None:\n        log.debug(f\"{self.__class__.__name__}: registering ddp hooks\")\n        # currently, DDP communication hooks only work with NCCL backend and SPSD (single process single device) mode\n        # https://github.com/pytorch/pytorch/blob/v1.8.0/torch/nn/parallel/distributed.py#L1080-L1084\n        if self.root_device.type == \"cuda\":\n            assert isinstance(self.model, DistributedDataParallel)\n            _register_ddp_comm_hook(\n                model=self.model,\n                ddp_comm_state=self._ddp_comm_state,\n                ddp_comm_hook=self._ddp_comm_hook,\n                ddp_comm_wrapper=self._ddp_comm_wrapper,\n            )\n\n    def _enable_model_averaging(self) -> None:\n        log.debug(f\"{self.__class__.__name__}: reinitializing optimizers with post localSGD\")\n        if self._model_averaging_period is None:\n            raise ValueError(\n                \"Post-localSGD algorithm is used, but model averaging period is not provided to DDP strategy.\"\n            )\n        from torch.distributed.optim import DistributedOptimizer, PostLocalSGDOptimizer, ZeroRedundancyOptimizer\n\n        for optimizer in self.optimizers:\n            if isinstance(optimizer, LightningOptimizer):\n                optimizer = optimizer._optimizer\n\n            is_distributed_optimizer = isinstance(optimizer, DistributedOptimizer) if not _IS_WINDOWS else False\n            if isinstance(optimizer, (ZeroRedundancyOptimizer, PostLocalSGDOptimizer)) or is_distributed_optimizer:\n                raise ValueError(\n                    f\"Currently model averaging cannot work with a distributed optimizer of type \"\n                    f\"{optimizer.__class__.__name__}.\"\n                )\n\n        assert self._ddp_comm_state is not None\n        self._model_averager = torch.distributed.algorithms.model_averaging.averagers.PeriodicModelAverager(\n            period=self._model_averaging_period, warmup_steps=self._ddp_comm_state.start_localSGD_iter","sourceCodeStart":232,"sourceCodeEnd":268,"githubUrl":"https://github.com/Lightning-AI/pytorch-lightning/blob/9fed5c27d2a62ff0efd6c3573599921d6ff67c14/src/lightning/pytorch/strategies/ddp.py#L232-L268","documentation":"When the DDP strategy is configured with post-localSGD (a communication hook enabling local SGD with periodic averaging), you must also pass model_averaging_period. _enable_model_averaging raises ValueError during setup if the period is missing, because PeriodicModelAverager cannot be constructed without it.","triggerScenarios":"Setting DDPStrategy(post_local_sgd=True) (or an equivalent comm hook config) without providing model_averaging_period to the strategy.","commonSituations":"Enabling post-localSGD after reading a tutorial that omitted the period argument; copying a strategy config where the period was set via a different parameter name across Lightning versions.","solutions":["Pass the averaging interval, e.g. DDPStrategy(post_local_sgd=True, model_averaging_period=10) (steps between synchronizations)","Or drop post_local_sgd=True if periodic model averaging is not intended"],"exampleFix":"# before\nstrategy = DDPStrategy(post_local_sgd=True)\n// after\nstrategy = DDPStrategy(post_local_sgd=True, model_averaging_period=10)","handlingStrategy":"validation","validationCode":"strategy = DDPStrategy(post_local_sgd=True)\nassert strategy._model_averaging_period is not None, \\\n    \"post_local_sgd requires model_averaging_period\"","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always set post_local_sgd and model_averaging_period together","Pin the Lightning version whose DDP strategy docs you followed"],"tags":["pytorch","lightning","ddp","distributed","post-local-sgd"],"backgroundTag":"missing-required-config-parameter","analyzedSha":"9fed5c27d2a62ff0efd6c3573599921d6ff67c14","analyzedAt":"2026-08-28T11:52:41.083Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}