{"record":{"id":"e66fcc195d5b170d","repo":"Lightning-AI/pytorch-lightning","slug":"do-not-set-gradient-accumulation-steps-in-the-de","errorCode":null,"errorMessage":"Do not set `gradient_accumulation_steps` in the DeepSpeed config as this will be set with the `accumulate_grad_batches` argument passed via the Lightning Trainer.","messagePattern":"Do not set `gradient_accumulation_steps` in the DeepSpeed config as this will be set with the `accumulate_grad_batches` argument passed via the Lightning Trainer\\.","errorType":"exception","errorClass":"MisconfigurationException","httpStatus":null,"severity":"error","filePath":"src/lightning/pytorch/strategies/deepspeed.py","lineNumber":924,"sourceCode":"                    \"pin_memory\": pin_memory,\n                }\n            cfg = {\n                \"zero_allow_untested_optimizer\": zero_allow_untested_optimizer,\n                \"zero_optimization\": zero_config,\n                **cfg,\n            }\n        if logging_batch_size_per_gpu != \"auto\":\n            cfg = {\"train_micro_batch_size_per_gpu\": logging_batch_size_per_gpu, **cfg}\n        return cfg\n\n    def _format_batch_size_and_grad_accum_config(self) -> None:\n        # TODO: Using Fabric, we do not support these variables within the config\n        assert isinstance(self.config, dict)\n        if self.lightning_module is None:\n            return\n\n        if \"gradient_accumulation_steps\" in self.config:\n            raise MisconfigurationException(\n                \"Do not set `gradient_accumulation_steps` in the DeepSpeed config\"\n                \" as this will be set with the `accumulate_grad_batches` argument passed via the Lightning Trainer.\"\n            )\n        self.config[\"gradient_accumulation_steps\"] = self.lightning_module.trainer.accumulate_grad_batches\n        if \"train_micro_batch_size_per_gpu\" not in self.config:\n            batch_size = self._auto_select_batch_size()\n            self.config[\"train_micro_batch_size_per_gpu\"] = batch_size\n        if \"gradient_clipping\" not in self.config:\n            self.config[\"gradient_clipping\"] = self.lightning_module.trainer.gradient_clip_val or 0.0\n\n    def _auto_select_batch_size(self) -> int:\n        # train_micro_batch_size_per_gpu is used for throughput logging purposes\n        # by default we try to use the batch size of the loader\n        assert self.lightning_module is not None\n        batch_size = 1\n        data_source = self.lightning_module.trainer.fit_loop._data_source\n        if data_source.is_defined():\n            train_dataloader = data_source.dataloader()","sourceCodeStart":906,"sourceCodeEnd":942,"githubUrl":"https://github.com/Lightning-AI/pytorch-lightning/blob/9fed5c27d2a62ff0efd6c3573599921d6ff67c14/src/lightning/pytorch/strategies/deepspeed.py#L906-L942","documentation":"The Trainer owns gradient accumulation and injects `gradient_accumulation_steps` into the DeepSpeed config from `Trainer(accumulate_grad_batches=...)`. A user-set value would conflict with the Trainer's, so _format_batch_size_and_grad_accum_config raises MisconfigurationException when the key is already present.","triggerScenarios":"Passing a DeepSpeed config dict/JSON that contains `gradient_accumulation_steps`, then calling `trainer.fit()` with DeepSpeedStrategy.","commonSituations":"Copying a DeepSpeed JSON from a pure-DeepSpeed (HuggingFace-style) script into Lightning; hand-tuned configs found online that include accumulation settings.","solutions":["Remove `gradient_accumulation_steps` from the DeepSpeed config and set it via `Trainer(accumulate_grad_batches=N)`","Keep all accumulation control in Lightning to guarantee the engine and loop agree"],"exampleFix":"# before\ncfg = {\"gradient_accumulation_steps\": 4, \"zero_optimization\": {\"stage\": 2}}\ntrainer = Trainer(strategy=DeepSpeedStrategy(config=cfg))\n\n# after\ncfg = {\"zero_optimization\": {\"stage\": 2}}\ntrainer = Trainer(strategy=DeepSpeedStrategy(config=cfg), accumulate_grad_batches=4)","handlingStrategy":"validation","validationCode":"ds_config.pop(\"gradient_accumulation_steps\", None)  # Lightning owns this key\ntrainer = Trainer(strategy=DeepSpeedStrategy(config=ds_config), accumulate_grad_batches=4)","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Strip Trainer-managed keys from imported DeepSpeed JSONs","Control accumulation only via Trainer(accumulate_grad_batches=...)"],"tags":["deepspeed","gradient-accumulation","config-conflict"],"backgroundTag":"config-key-conflict","analyzedSha":"9fed5c27d2a62ff0efd6c3573599921d6ff67c14","analyzedAt":"2026-08-28T11:52:41.083Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}