{"record":{"id":"6b63a37d25a2d1fc","repo":"Lightning-AI/pytorch-lightning","slug":"deepspeed-does-not-support-clipping-gradients-by-v","errorCode":null,"errorMessage":"DeepSpeed does not support clipping gradients by value.","messagePattern":"DeepSpeed does not support clipping gradients by value\\.","errorType":"exception","errorClass":"MisconfigurationException","httpStatus":null,"severity":"error","filePath":"src/lightning/pytorch/strategies/deepspeed.py","lineNumber":471,"sourceCode":"            lr_scheduler=lr_scheduler,\n            dist_init_required=False,\n        )\n        return deepspeed_engine, deepspeed_optimizer\n\n    def init_deepspeed(self) -> None:\n        assert self.lightning_module is not None\n        # deepspeed handles gradient clipping internally\n        if is_overridden(\"configure_gradient_clipping\", self.lightning_module, pl.LightningModule):\n            rank_zero_warn(\n                \"Since DeepSpeed handles gradient clipping internally, the default\"\n                \" `LightningModule.configure_gradient_clipping` implementation will not actually clip gradients.\"\n                \" The hook will still be called. Consider setting\"\n                \" `Trainer(gradient_clip_val=..., gradient_clip_algorithm='norm')`\"\n                \" which will use the internal mechanism.\"\n            )\n\n        if self.lightning_module.trainer.gradient_clip_algorithm == GradClipAlgorithmType.VALUE:\n            raise MisconfigurationException(\"DeepSpeed does not support clipping gradients by value.\")\n\n        assert isinstance(self.model, pl.LightningModule)\n        if self.lightning_module.trainer and self.lightning_module.trainer.training:\n            self._initialize_deepspeed_train(self.model)\n        else:\n            self._initialize_deepspeed_inference(self.model)\n\n    def _init_optimizers(self) -> tuple[Optimizer, Optional[LRSchedulerConfig]]:\n        assert self.lightning_module is not None\n        optimizers, lr_schedulers = _init_optimizers_and_lr_schedulers(self.lightning_module)\n        if len(optimizers) > 1 or len(lr_schedulers) > 1:\n            raise MisconfigurationException(\n                \"DeepSpeed currently only supports single optimizer, single optional scheduler.\"\n            )\n        return optimizers[0], lr_schedulers[0] if lr_schedulers else None\n\n    @property\n    def zero_stage_3(self) -> bool:","sourceCodeStart":453,"sourceCodeEnd":489,"githubUrl":"https://github.com/Lightning-AI/pytorch-lightning/blob/9fed5c27d2a62ff0efd6c3573599921d6ff67c14/src/lightning/pytorch/strategies/deepspeed.py#L453-L489","documentation":"DeepSpeed clips gradients internally (via its config `gradient_clipping`) and only supports norm-based clipping; value-based clipping (`gradient_clip_algorithm='value'`) has no DeepSpeed equivalent, so Lightning raises MisconfigurationException at engine init.","triggerScenarios":"`Trainer(strategy=DeepSpeedStrategy(...), gradient_clip_val=X, gradient_clip_algorithm=\"value\")`, or the equivalent LightningModule `configure_gradient_clipping` expecting value clipping — detected in `init_deepspeed` before the engine is built.","commonSituations":"Porting a recipe that used value clipping under DDP; default Trainer flags copied from another project. Fix: use `gradient_clip_algorithm=\"norm\"` (or omit it) and optionally set gradient_clipping in the DeepSpeed config.","solutions":["Switch to `Trainer(..., gradient_clip_val=X, gradient_clip_algorithm=\"norm\")`","Or drop the Trainer clipping arg and set `gradient_clipping` in the DeepSpeed config dict","Avoid `configure_gradient_clipping` implementations that rely on value clipping under DeepSpeed"],"exampleFix":"# before\ntrainer = Trainer(strategy=DeepSpeedStrategy(config=cfg), gradient_clip_val=1.0, gradient_clip_algorithm=\"value\")\n\n# after\ntrainer = Trainer(strategy=DeepSpeedStrategy(config=cfg), gradient_clip_val=1.0, gradient_clip_algorithm=\"norm\")","handlingStrategy":"validation","validationCode":"algo = \"norm\"  # ensure value never reaches DeepSpeed\ntrainer = Trainer(strategy=DeepSpeedStrategy(config=cfg), gradient_clip_val=1.0, gradient_clip_algorithm=algo)","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Default to gradient_clip_algorithm='norm' in shared configs","Set gradient clipping in the DeepSpeed config instead of Trainer flags when possible"],"tags":["deepspeed","gradient-clipping","trainer-flags"],"backgroundTag":"unsupported-trainer-option","analyzedSha":"9fed5c27d2a62ff0efd6c3573599921d6ff67c14","analyzedAt":"2026-08-28T11:52:41.083Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}