{"record":{"id":"3a217b450fba9da3","repo":"Lightning-AI/pytorch-lightning","slug":"to-use-deepspeed-you-must-pass-in-a-deepspeed-conf","errorCode":null,"errorMessage":"To use DeepSpeed you must pass in a DeepSpeed config dict, or a path to a JSON config. See: https://lightning.ai/docs/pytorch/stable/advanced/model_parallel.html#deepspeed","messagePattern":"To use DeepSpeed you must pass in a DeepSpeed config dict, or a path to a JSON config\\. See: https://lightning\\.ai/docs/pytorch/stable/advanced/model_parallel\\.html#deepspeed","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/lightning/fabric/strategies/deepspeed.py","lineNumber":701,"sourceCode":"        os.environ[\"LOCAL_RANK\"] = str(self.local_rank)\n\n    def _set_deepspeed_activation_checkpointing(self) -> None:\n        import deepspeed\n\n        assert isinstance(self.config, dict)\n        if self.config.get(\"activation_checkpointing\"):\n            checkpoint_config = self.config[\"activation_checkpointing\"]\n            deepspeed.checkpointing.configure(\n                mpu_=None,\n                partition_activations=checkpoint_config.get(\"partition_activations\"),\n                contiguous_checkpointing=checkpoint_config.get(\"contiguous_memory_optimization\"),\n                checkpoint_in_cpu=checkpoint_config.get(\"cpu_checkpointing\"),\n                profile=checkpoint_config.get(\"profile\"),\n            )\n\n    def _format_config(self) -> None:\n        if self.config is None:\n            raise ValueError(\n                \"To use DeepSpeed you must pass in a DeepSpeed config dict, or a path to a JSON config.\"\n                \" See: https://lightning.ai/docs/pytorch/stable/advanced/model_parallel.html#deepspeed\"\n            )\n\n        self.config.setdefault(\"train_micro_batch_size_per_gpu\", 1)\n        _format_precision_config(\n            config=self.config,\n            precision=self.precision.precision,\n            loss_scale=self.loss_scale,\n            loss_scale_window=self.loss_scale_window,\n            min_loss_scale=self.min_loss_scale,\n            initial_scale_power=self.initial_scale_power,\n            hysteresis=self.hysteresis,\n        )\n\n    def _create_default_config(\n        self,\n        zero_optimization: bool,","sourceCodeStart":683,"sourceCodeEnd":719,"githubUrl":"https://github.com/Lightning-AI/pytorch-lightning/blob/9fed5c27d2a62ff0efd6c3573599921d6ff67c14/src/lightning/fabric/strategies/deepspeed.py#L683-L719","documentation":"DeepSpeedStrategy needs a DeepSpeed configuration to initialize the engine. _format_config raises ValueError when self.config is None (no dict, no JSON path, and no DEEPSPEED_ENV_VAR was set), because there is no way to infer all engine settings.","triggerScenarios":"Creating DeepSpeedStrategy() with config=None while the DEEPSPEED_ENV_VAR environment variable is unset, then running setup; or Fabric/Trainer automatically selecting the deepspeed strategy without a config on a machine where the env var is absent.","commonSituations":"Selecting strategy=\"deepspeed\" in the Trainer without passing a config; env-var-based config works in a launcher script but not in an interactive shell/SLURM job where the variable is not exported; typo in the env variable name.","solutions":["Pass a config: DeepSpeedStrategy(config=\"ds_config.json\") or config={...}","Or export the environment variable the strategy reads: DEEPSPEED_CONFIG_FILE (check strategy.DEEPSPEED_ENV_VAR) pointing to the JSON file","Verify the env var is actually exported in the process running the training (print os.environ)"],"exampleFix":"# before\nstrategy = DeepSpeedStrategy()\n\n# after\nstrategy = DeepSpeedStrategy(config={\"train_batch_size\": 8, \"optimizer\": {\"type\": \"Adam\"}})","handlingStrategy":"validation","validationCode":"import os\nfrom lightning.fabric.strategies import DeepSpeedStrategy\nif DeepSpeedStrategy.DEEPSPEED_ENV_VAR not in os.environ:\n    assert config is not None, \"pass DeepSpeedStrategy(config=...) or export the env var\"","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always pass an explicit config dict/path","Document the env-var dependency in launch scripts"],"tags":["deepspeed","config","missing-argument"],"backgroundTag":"missing-config","analyzedSha":"9fed5c27d2a62ff0efd6c3573599921d6ff67c14","analyzedAt":"2026-08-28T11:52:41.083Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}